{ "openapi": "3.1.0", "info": { "title": "Sukidata API", "version": "1.0.0", "description": "通过各产品 API 获取网页数据、生成或编辑图片。" }, "servers": [ { "url": "https://api.sukidata.com" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "搜索", "description": "创建并查询 Google SERP 搜索。" }, { "name": "Twitter 时间线", "description": "获取 Twitter 用户公开时间线中的帖子。" }, { "name": "搜索配置", "description": "查看可用的搜索定位参数。" }, { "name": "请求记录", "description": "查看当前 Workspace 的 Web Data 请求记录。" }, { "name": "结果文件", "description": "获取生成的 JSON 和 HTML 结果文件。" }, { "name": "API 规范", "description": "获取机器可读的 API 规范。" }, { "name": "图片", "description": "根据提示词生成图片，或编辑参考图片。" }, { "name": "可用模型", "description": "查看可用的 AI 模型。" }, { "name": "图片任务", "description": "查询图片任务进度和结果。" } ], "x-tagGroups": [ { "name": "通用", "tags": [ "API 规范" ] }, { "name": "Web Data", "tags": [ "搜索", "Twitter 时间线", "搜索配置", "请求记录", "结果文件" ] }, { "name": "AI", "tags": [ "可用模型", "图片", "图片任务" ] } ], "paths": { "/openapi.json": { "get": { "operationId": "getOpenApiDocument", "summary": "获取 OpenAPI 文档", "tags": [ "API 规范" ], "security": [], "responses": { "200": { "description": "OpenAPI 3.1 JSON 文档。", "content": { "application/json": { "schema": { "type": "object" } } } }, "500": { "$ref": "#/components/responses/ServiceError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/activity": { "get": { "operationId": "listSearchActivity", "summary": "列出搜索记录", "tags": [ "请求记录" ], "parameters": [ { "$ref": "#/components/parameters/ListLimit" }, { "$ref": "#/components/parameters/ListCursor" }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 512 }, "description": "按搜索 ID、请求 ID、搜索词、Twitter 用户名或用户 ID，以及位置搜索。" }, { "name": "endpoint", "in": "query", "schema": { "type": "string", "enum": [ "serp", "/v1/serp", "twitter", "/v1/twitter" ] }, "description": "按产品名或其 `/v1/...` 路径筛选。" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "success", "running", "failed", "cache" ] }, "description": "按状态筛选，`cache` 返回缓存响应。" }, { "name": "api_key_id", "in": "query", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "description": "按 API Key ID 筛选。" }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "`created_at` 的起始时间，包含该时刻。" } ], "responses": { "200": { "description": "当前 Workspace 的近期请求记录。", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServiceError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/activity/{search_id}": { "get": { "operationId": "getSearchActivity", "summary": "获取搜索记录", "tags": [ "请求记录" ], "parameters": [ { "name": "search_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } } ], "responses": { "200": { "description": "当前 Workspace 的请求详情。", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServiceError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/serp/locations": { "get": { "operationId": "searchGoogleLocations", "summary": "搜索支持的位置", "tags": [ "搜索配置" ], "security": [], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 4096 }, "description": "可选。输入位置搜索词；省略时列出支持的 Google 位置。" }, { "name": "limit", "in": "query", "description": "最多返回的位置数量，默认为 10。", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 10 } } ], "responses": { "200": { "description": "匹配且受支持的 Google 位置。", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleLocations" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServiceError" } } } }, "/v1/serp/google-support": { "get": { "operationId": "listGoogleSearchParameters", "summary": "列出支持的 Google 参数", "tags": [ "搜索配置" ], "security": [], "responses": { "200": { "description": "支持的 Google 域名、国家或地区代码、界面语言及限制令牌。", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleSupport" } } } }, "500": { "$ref": "#/components/responses/ServiceError" } } } }, "/v1/serp": { "post": { "operationId": "createSerpSearch", "summary": "创建 SERP 搜索", "tags": [ "搜索" ], "parameters": null, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SERPRequest" }, "example": { "q": "coffee shops in seattle", "location": "Seattle, Washington, United States", "hl": "en" } } } }, "responses": { "200": { "description": "搜索状态、完成结果或失败结果。", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "X-Sukidata-Cache-Hit": { "$ref": "#/components/headers/SukidataCacheHit" }, "X-Sukidata-Credits-Used": { "$ref": "#/components/headers/SukidataCreditsUsed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SERPEnvelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/ServiceError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "callbacks": { "serpWebhook": { "{$request.body#/webhook/url}": { "post": { "summary": "可选的 SERP Webhook 通知。", "description": "当请求提供 `webhook.url` 并订阅匹配事件时发送；发送失败时可能重试。", "parameters": [ { "name": "X-Sukidata-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "serp.search.queued", "serp.search.processing", "serp.search.completed", "serp.search.failed" ] } }, { "name": "X-Sukidata-Delivery", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Sukidata-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Sukidata-Signature", "in": "header", "required": false, "schema": { "type": "string" }, "description": "当 API 密钥配置了 Webhook 密钥时，以 `v1=` 格式提供 HMAC 签名。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "2XX": { "description": "Webhook 端点已接受通知。" } } } } } } } }, "/v1/serp/{search_id}": { "get": { "operationId": "getSerpSearch", "summary": "获取 SERP 搜索", "tags": [ "搜索" ], "parameters": [ { "name": "search_id", "in": "path", "required": true, "description": "POST /v1/serp 返回的搜索 ID。格式错误时返回 400；当前 Workspace 无权访问时返回 404。", "schema": { "type": "string", "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$" } } ], "responses": { "200": { "description": "搜索状态、完成结果或失败结果。", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "X-Sukidata-Cache-Hit": { "$ref": "#/components/headers/SukidataCacheHit" }, "X-Sukidata-Credits-Used": { "$ref": "#/components/headers/SukidataCreditsUsed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SERPEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServiceError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/twitter": { "post": { "operationId": "createTwitterSearch", "summary": "获取 Twitter 用户时间线", "description": "获取指定用户的一页公开帖子。后续请求可将 `next_cursor` 作为 `cursor` 传入以继续获取。成功请求按实际返回数量计费，每 10 条消耗 1 积分，不足 10 条按 10 条计算，最低 1 积分。", "tags": [ "Twitter 时间线" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TwitterRequest" }, "example": { "username": "sukidata", "max_results": 20 } } } }, "responses": { "200": { "description": "请求状态、完整时间线结果或失败结果。", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "X-Sukidata-Cache-Hit": { "$ref": "#/components/headers/SukidataCacheHit" }, "X-Sukidata-Credits-Used": { "$ref": "#/components/headers/SukidataCreditsUsed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TwitterEnvelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/ServiceError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "callbacks": { "twitterWebhook": { "{$request.body#/webhook/url}": { "post": { "summary": "可选的 Twitter Webhook 通知。", "description": "当请求提供 `webhook.url` 并订阅匹配事件时发送；发送失败时可能重试。", "parameters": [ { "name": "X-Sukidata-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "twitter.search.queued", "twitter.search.processing", "twitter.search.completed", "twitter.search.failed" ] } }, { "name": "X-Sukidata-Delivery", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Sukidata-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Sukidata-Signature", "in": "header", "required": false, "schema": { "type": "string" }, "description": "当 API 密钥配置了 Webhook 密钥时，以 `v1=` 格式提供 HMAC 签名。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TwitterWebhookPayload" } } } }, "responses": { "2XX": { "description": "Webhook 端点已接受通知。" } } } } } } } }, "/v1/twitter/{search_id}": { "get": { "operationId": "getTwitterSearch", "summary": "获取 Twitter 时间线请求", "tags": [ "Twitter 时间线" ], "parameters": [ { "name": "search_id", "in": "path", "required": true, "description": "POST /v1/twitter 返回的搜索 ID。格式错误时返回 400；当前 Workspace 无权访问时返回 404。", "schema": { "type": "string", "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$" } } ], "responses": { "200": { "description": "请求状态、完整时间线结果或失败结果。", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "X-Sukidata-Cache-Hit": { "$ref": "#/components/headers/SukidataCacheHit" }, "X-Sukidata-Credits-Used": { "$ref": "#/components/headers/SukidataCreditsUsed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TwitterEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServiceError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/models": { "get": { "operationId": "listModels", "summary": "列出可用 AI 模型", "description": "列出当前 API Key 可用的模型。", "tags": [ "可用模型" ], "responses": { "200": { "description": "采用 OpenAI 兼容列表格式的可用模型。", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AIModel" } } } } } } }, "default": { "$ref": "#/components/responses/ImageError" } } } }, "/v1/images/generations": { "post": { "operationId": "generateImages", "summary": "生成图片", "description": "根据提示词生成图片，可选用参考图。默认返回 Base64，设置 response_format 为 url 可获取图片链接。", "tags": [ "图片" ], "parameters": [ { "$ref": "#/components/parameters/ImageIdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/ImageGeneration" }, "responses": { "200": { "$ref": "#/components/responses/ImageResult" }, "default": { "$ref": "#/components/responses/ImageError" } } } }, "/v1/images/generations/async": { "post": { "operationId": "generateImagesAsync", "summary": "提交异步图片生成", "description": "提交图片生成任务，通过 Location 响应头中的地址查询进度与结果。", "tags": [ "图片" ], "parameters": [ { "$ref": "#/components/parameters/ImageIdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/ImageGeneration" }, "responses": { "202": { "$ref": "#/components/responses/ImageAccepted" }, "default": { "$ref": "#/components/responses/ImageError" } } } }, "/v1/images/edits": { "post": { "operationId": "editImages", "summary": "编辑图片", "description": "使用提示词和参考图编辑图片。通过 multipart/form-data 上传文件，或通过 JSON 提交图片 URL；可选蒙版用于指定编辑区域。", "tags": [ "图片" ], "parameters": [ { "$ref": "#/components/parameters/ImageIdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/ImageEdit" }, "responses": { "200": { "$ref": "#/components/responses/ImageResult" }, "default": { "$ref": "#/components/responses/ImageError" } } } }, "/v1/images/edits/async": { "post": { "operationId": "editImagesAsync", "summary": "提交异步图片编辑", "description": "提交图片编辑任务，参数和输入限制与同步编辑相同。", "tags": [ "图片" ], "parameters": [ { "$ref": "#/components/parameters/ImageIdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/ImageEdit" }, "responses": { "202": { "$ref": "#/components/responses/ImageAccepted" }, "default": { "$ref": "#/components/responses/ImageError" } } } }, "/v1/images/tasks": { "get": { "operationId": "listImageTasks", "summary": "列出图片任务", "description": "列出当前 Workspace 的图片任务，包含状态、费用和图片链接。", "tags": [ "图片任务" ], "parameters": [ { "$ref": "#/components/parameters/ListLimit" }, { "$ref": "#/components/parameters/ListCursor" }, { "name": "model", "in": "query", "schema": { "type": "string", "maxLength": 128 } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/ImageTaskStatus" } }, { "name": "search", "in": "query", "description": "按提示词或任务 ID 搜索。", "schema": { "type": "string", "maxLength": 256 } }, { "name": "operation", "in": "query", "schema": { "enum": [ "images.generations", "images.edits" ] } }, { "name": "api_key_id", "in": "query", "description": "按提交请求的密钥 ID 筛选，包括已删除的密钥。省略时包含所有来源及 Playground 请求。", "schema": { "type": "string", "maxLength": 128 } }, { "name": "created_from", "in": "query", "description": "创建时间下界（包含），使用带时区的 RFC 3339 时间戳。", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_to", "in": "query", "description": "创建时间上界（不包含），使用带时区的 RFC 3339 时间戳，必须晚于 created_from。", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "按创建时间从新到旧返回任务。", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "next_cursor" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ImageTaskSummary" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "default": { "$ref": "#/components/responses/ImageError" } } } }, "/v1/images/tasks/{task_id}": { "get": { "operationId": "getImageTask", "summary": "获取图片任务", "description": "获取任务的提示词、参数、状态、图片和费用，须使用同一 Workspace 的 API Key。", "tags": [ "图片任务" ], "parameters": [ { "$ref": "#/components/parameters/ImageTaskID" } ], "responses": { "200": { "description": "图片任务详情。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageTask" } } } }, "default": { "$ref": "#/components/responses/ImageError" } } } }, "/searches/{file_token}/{search_id}.{format}": { "servers": [ { "url": "https://files.sukidata.com" } ], "get": { "operationId": "getSearchResultFile", "summary": "获取结果文件", "tags": [ "结果文件" ], "description": "返回 `search_metadata.json_endpoint` 或 `search_metadata.raw_html_file` 指向的结果文件。文件 URL 无需 API 认证并保留一个月，请勿公开；仅抓取源页面的产品提供 HTML 文件。", "security": [], "parameters": [ { "name": "file_token", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "search_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "format", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "json", "html" ] } } ], "responses": { "200": { "description": "`.json` 返回 JSON 搜索结果，`.html` 返回 HTML 快照。", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "结果文件的缓存策略。" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SERPEnvelope" }, { "$ref": "#/components/schemas/TwitterEnvelope" } ] } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } } }, "components": { "parameters": { "ImageIdempotencyKey": { "name": "Idempotency-Key", "in": "header", "description": "重试同一任务时保持此键、参数和文件不变。键的作用域为 Workspace 和操作，同步与异步提交共用；更改输入返回 409，使用新键会创建新任务。上传中断须在任务创建后十分钟内重试；到期后任务失败、不收费，重新提交须使用新键。", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" } }, "ImageTaskID": { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, "ListLimit": { "name": "limit", "in": "query", "description": "最多返回的记录数量，默认为 20。", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "ListCursor": { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "上一页列表响应返回的不透明游标。" } }, "headers": { "ImageTaskID": { "description": "任务创建后返回的 ID，可在超时后用于查询结果。", "schema": { "type": "string" } }, "RequestID": { "description": "联系支持团队时需提供的请求标识。", "schema": { "$ref": "#/components/schemas/RequestID" } }, "SukidataCacheHit": { "description": "该请求是否符合零积分缓存响应条件。", "schema": { "type": "boolean" } }, "SukidataCreditsUsed": { "description": "搜索达到 `Success` 或 `Error` 状态后扣除的积分。进行中不返回，缓存响应为 `0`。", "schema": { "type": "integer", "format": "int64" } } }, "responses": { "ImageResult": { "description": "生成的图片。", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "X-Sukidata-Task-ID": { "$ref": "#/components/headers/ImageTaskID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResult" } } } }, "ImageAccepted": { "description": "任务 ID 和当前状态，复用幂等键时返回同一任务。", "headers": { "X-Sukidata-Task-ID": { "$ref": "#/components/headers/ImageTaskID" }, "Location": { "description": "需鉴权的任务详情及进度查询地址。", "schema": { "type": "string", "format": "uri" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "object", "status" ], "properties": { "id": { "type": "string" }, "object": { "const": "image.task" }, "status": { "$ref": "#/components/schemas/ImageTaskStatus" } } } } } }, "ImageError": { "description": "HTTP 错误：400 输入或模型无效；401 API Key 缺失或无效；402 AI 余额不足；403 无权访问；404 任务不存在；409 幂等键冲突；410 上传或图片链接到期；413 请求过大；502 生成失败；503 服务暂不可用或结果待确认。若返回 X-Sukidata-Task-ID，请先查询原任务再重试。", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "X-Sukidata-Task-ID": { "$ref": "#/components/headers/ImageTaskID" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/ImageErrorDetail" } } } } } }, "BadRequest": { "description": "请求参数无效。", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Unauthorized": { "description": "API 密钥缺失、无效、未启用、已撤销或已过期。", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "PaymentRequired": { "description": "积分不足，未创建搜索。", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Forbidden": { "description": "此 API Key 无权访问。", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "NotFound": { "description": "当前 Workspace 中未找到该搜索。", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "PayloadTooLarge": { "description": "请求体过大。", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "UnsupportedMediaType": { "description": "请求的 Content-Type 必须为 application/json。", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "ServiceError": { "description": "服务发生意外错误。", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "ServiceUnavailable": { "description": "服务暂时不可用。", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBodies": { "ImageGeneration": { "required": true, "description": "JSON 或 multipart 请求，最大 48 MiB。可选参考图须为 PNG、JPEG 或 WebP，参考图数量上限由所选模型决定。", "content": { "application/json": { "example": { "model": "gpt-image-2.5", "prompt": "A blue ceramic cup on a plain white background" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/ImageRequestFields" }, { "$ref": "#/components/schemas/ImageReferenceFields" } ], "unevaluatedProperties": false } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ImageRequestFields" }, { "$ref": "#/components/schemas/ImageMultipartFields" } ], "unevaluatedProperties": false } } } }, "ImageEdit": { "required": true, "description": "JSON 或 multipart 请求，至少包含一张参考图，请求体最大 48 MiB。输入支持 PNG、JPEG、WebP，参考图数量上限由所选模型决定。", "content": { "application/json": { "example": { "model": "gpt-image-2.5", "prompt": "Change the cup to green, keeping the composition", "images": [ { "image_url": "https://example.com/input.png" } ] }, "schema": { "allOf": [ { "$ref": "#/components/schemas/ImageRequestFields" }, { "$ref": "#/components/schemas/ImageReferenceFields" }, { "type": "object", "anyOf": [ { "required": [ "image" ] }, { "required": [ "images" ] } ], "properties": { "mask": { "$ref": "#/components/schemas/ImageMask" } } } ], "unevaluatedProperties": false } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ImageRequestFields" }, { "$ref": "#/components/schemas/ImageMultipartFields" }, { "type": "object", "anyOf": [ { "required": [ "image" ] }, { "required": [ "image[]" ] } ], "properties": { "mask": { "type": "string", "format": "binary", "description": "带 alpha 通道的 PNG 蒙版，尺寸须与第一张参考图一致。透明区域指定编辑位置，蒙版不占用参考图数量名额。" } } } ], "unevaluatedProperties": false } } } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "在 Sukidata 控制台创建的 API 密钥。" } }, "schemas": { "ImageReferenceFields": { "type": "object", "description": "从 image 和 images 中选择一个字段，两者均支持单张参考图或数组。", "not": { "required": [ "image", "images" ] }, "properties": { "image": { "$ref": "#/components/schemas/ImageReferences" }, "images": { "$ref": "#/components/schemas/ImageReferences" } } }, "ImageReferences": { "oneOf": [ { "$ref": "#/components/schemas/ImageReference" }, { "type": "array", "minItems": 1, "maxItems": 16, "items": { "$ref": "#/components/schemas/ImageReference" } } ] }, "ImageReference": { "oneOf": [ { "type": "string", "minLength": 1, "description": "公开 HTTPS 图片 URL，或 PNG、JPEG、WebP 的 Base64 data URL。" }, { "type": "object", "additionalProperties": false, "properties": { "image_url": { "type": "string", "minLength": 1, "description": "公开 HTTPS 图片 URL，或 PNG、JPEG、WebP 的 Base64 data URL。" }, "b64_json": { "type": "string", "minLength": 1, "contentEncoding": "base64", "description": "Base64 编码的 PNG、JPEG 或 WebP 参考图。" } }, "oneOf": [ { "required": [ "image_url" ] }, { "required": [ "b64_json" ] } ] } ] }, "ImageMask": { "allOf": [ { "$ref": "#/components/schemas/ImageReference" } ], "description": "带 alpha 通道的 PNG 蒙版，尺寸须与第一张参考图一致。透明区域指定编辑位置，蒙版不占用参考图数量名额。" }, "ImageMultipartFields": { "type": "object", "properties": { "image": { "type": "string", "format": "binary", "description": "PNG、JPEG 或 WebP 文件，多张图片使用重复的 image[] 字段。" }, "image[]": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "string", "format": "binary" } } } }, "AIModel": { "type": "object", "required": [ "id", "object", "created", "owned_by" ], "properties": { "id": { "type": "string" }, "object": { "const": "model" }, "created": { "type": "integer", "format": "int64", "description": "以秒为单位的 Unix 时间戳。" }, "owned_by": { "const": "sukidata" } } }, "ImageRequestFields": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 128, "description": "/v1/models 返回的可用模型 ID，例如 gpt-image-2.5 或 gpt-image-2。" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 32000 }, "size": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^(auto|[1-9][0-9]{0,3}x[1-9][0-9]{0,3})$", "description": "请求尺寸为 auto 或 WIDTHxHEIGHT。宽高须为不超过 3840 的正整数，宽高比介于 1:3 和 3:1，总像素介于 655360 和 8294400。省略时使用模型默认值。" }, "quality": { "type": "string", "minLength": 1, "maxLength": 16, "description": "所选模型支持的质量，省略时使用模型默认值。" }, "n": { "type": "integer", "minimum": 1, "maximum": 10, "description": "生成图片的张数，受所选模型上限限制。gpt-image-2.5 和 gpt-image-2 每次支持 1–4 张，默认 1 张。" }, "output_format": { "type": "string", "enum": [ "png", "jpeg", "webp" ], "default": "png" }, "background": { "type": "string", "enum": [ "auto", "opaque", "transparent" ], "description": "透明背景输出须使用 PNG 或 WebP。" }, "moderation": { "type": "string", "enum": [ "auto", "low" ] }, "output_compression": { "type": "integer", "minimum": 0, "maximum": 100, "description": "JPEG 和 WebP 的输出压缩参数，PNG 接收此参数但不应用。" }, "response_format": { "type": "string", "enum": [ "b64_json", "url" ], "default": "b64_json", "description": "同步响应的交付格式。异步任务通过详情中的公共图片 URL 交付。" }, "stream": { "type": "boolean", "const": false, "description": "设为 false 或省略，需要后台生成时使用异步接口。" }, "user": { "type": "string", "maxLength": 256, "description": "调用方的终端用户标识，随任务保存。" } } }, "ImageResult": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ImageResultMetadata" } ], "required": [ "created", "data" ], "properties": { "created": { "type": "integer", "format": "int64", "description": "任务创建时间，以秒为单位的 Unix 时间戳。" }, "data": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "oneOf": [ { "required": [ "b64_json" ] }, { "required": [ "url" ] } ], "properties": { "b64_json": { "type": "string", "contentEncoding": "base64" }, "url": { "type": "string", "format": "uri", "description": "图片 URL，自发布起可用 31 天，持有链接的人均可查看。" } } } } } }, "ImageResultMetadata": { "type": "object", "description": "输出信息，有数据时返回。多张图片尺寸不同时省略顶层 size，各图片尺寸可在任务详情的 images 数组中查看。", "properties": { "background": { "enum": [ "opaque", "transparent" ] }, "output_format": { "enum": [ "png", "jpeg", "webp" ] }, "size": { "type": "string" }, "quality": { "enum": [ "low", "medium", "high", "xhigh", "max" ] }, "usage": { "$ref": "#/components/schemas/ImageTokenUsage" } } }, "ImageTokenUsage": { "type": "object", "required": [ "input_tokens", "output_tokens", "total_tokens" ], "description": "Token 用量，有数据时返回；按张计费不会额外收取 token 费用。", "properties": { "input_tokens": { "type": "integer", "minimum": 0 }, "output_tokens": { "type": "integer", "minimum": 0 }, "total_tokens": { "type": "integer", "minimum": 0 }, "input_tokens_details": { "$ref": "#/components/schemas/ImageTokenDetails" }, "output_tokens_details": { "$ref": "#/components/schemas/ImageTokenDetails" } } }, "ImageTokenDetails": { "type": "object", "properties": { "text_tokens": { "type": "integer", "minimum": 0 }, "image_tokens": { "type": "integer", "minimum": 0 }, "cached_tokens": { "type": "integer", "minimum": 0 } } }, "ImageTaskStatus": { "type": "string", "enum": [ "queued", "processing", "completed", "failed", "unknown" ], "description": "任务进度。unknown 表示结果尚未确认，并非已确认失败；请继续查询同一个任务。" }, "ImageContentStatus": { "type": "string", "enum": [ "pending", "ready", "unavailable" ], "description": "生成图片文件的可用状态。" }, "ImageTaskSummary": { "type": "object", "required": [ "id", "model", "operation", "prompt_preview", "status", "content_status", "billing_status", "billing", "api_key_id", "image_count", "images", "created_at", "completed_at", "url" ], "properties": { "id": { "type": "string" }, "model": { "type": "string" }, "operation": { "enum": [ "images.generations", "images.edits" ] }, "prompt_preview": { "type": "string" }, "status": { "$ref": "#/components/schemas/ImageTaskStatus" }, "content_status": { "$ref": "#/components/schemas/ImageContentStatus" }, "billing_status": { "type": "string", "description": "计费状态，已完成任务的费用可能仍待确认。" }, "billing": { "$ref": "#/components/schemas/ImageBilling" }, "api_key_id": { "type": [ "string", "null" ], "description": "提交任务时使用的 API Key ID，无法获取时为 null。" }, "image_count": { "type": "integer", "minimum": 0, "description": "本次响应中可获取的生成图片数量。" }, "images": { "type": "array", "description": "图片链接与到期时间，图片就绪前为空。", "items": { "type": "object", "required": [ "index", "url", "width", "height" ], "properties": { "index": { "type": "integer", "minimum": 0 }, "url": { "type": "string", "format": "uri" }, "url_expires_at": { "type": "string", "format": "date-time", "description": "公开链接到期时间。请在到期前保存图片，到期后无法通过 API 取回。" }, "thumbnail_url": { "type": "string", "format": "uri", "description": "缩略图就绪后返回此链接，与原图同时到期。完整分辨率图片请使用 url。" }, "width": { "type": "integer", "minimum": 1, "description": "原图宽度，单位为像素。" }, "height": { "type": "integer", "minimum": 1, "description": "原图高度，单位为像素。" } } } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "url": { "type": "string", "format": "uri", "description": "任务详情地址，需要 API 鉴权。" } } }, "ImageFile": { "type": "object", "required": [ "index", "url", "width", "height", "format" ], "properties": { "index": { "type": "integer", "minimum": 0 }, "url": { "type": "string", "format": "uri" }, "url_expires_at": { "type": "string", "format": "date-time", "description": "公开链接到期时间。请在到期前保存图片，到期后无法通过 API 取回。" }, "thumbnail_url": { "type": "string", "format": "uri", "description": "缩略图就绪后返回此链接，与原图同时到期。完整分辨率图片请使用 url。" }, "width": { "type": "integer", "minimum": 1 }, "height": { "type": "integer", "minimum": 1 }, "format": { "enum": [ "png", "jpeg", "webp" ] } } }, "ImageTask": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ImageResultMetadata" } ], "required": [ "id", "object", "model", "operation", "status", "content_status", "created_at", "completed_at", "prompt", "parameters", "images", "billing" ], "properties": { "id": { "type": "string" }, "object": { "const": "image.task" }, "model": { "type": "string" }, "operation": { "enum": [ "images.generations", "images.edits" ] }, "status": { "$ref": "#/components/schemas/ImageTaskStatus" }, "content_status": { "$ref": "#/components/schemas/ImageContentStatus" }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "prompt": { "type": "string" }, "parameters": { "type": "object", "description": "提交此任务时使用的参数。" }, "effective_parameters": { "type": "object", "description": "任务采用的尺寸、质量和张数，包含模型默认值。其他设置见 parameters。", "properties": { "size": { "type": "string" }, "quality": { "type": "string" }, "n": { "type": "integer" } } }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/ImageFile" } }, "billing": { "$ref": "#/components/schemas/ImageBilling" }, "error": { "$ref": "#/components/schemas/ImageErrorDetail" } } }, "ImageBilling": { "type": "object", "required": [ "balance_type", "currency", "status", "reserved_amount", "charged_amount" ], "properties": { "balance_type": { "const": "ai" }, "currency": { "const": "USD" }, "status": { "type": "string", "enum": [ "pending", "reserved", "review", "settled", "released", "rejected", "unavailable" ], "description": "计费状态，unavailable 时金额字段为 null。" }, "reserved_amount": { "type": [ "string", "null" ], "pattern": "^[0-9]+\\.[0-9]{9}$", "description": "当前为此任务预留的美元金额，待确认或暂不可用时为 null。" }, "charged_amount": { "type": [ "string", "null" ], "pattern": "^[0-9]+\\.[0-9]{9}$", "description": "更正后的实际美元费用，待确认或暂不可用时为 null。" }, "original_charged_amount": { "type": [ "string", "null" ], "pattern": "^[0-9]+\\.[0-9]{9}$", "description": "更正前的原始美元费用，待确认或暂不可用时为 null。" }, "credited_amount": { "type": [ "string", "null" ], "pattern": "^[0-9]+\\.[0-9]{9}$", "description": "此任务退回 AI 余额的美元金额，待确认或暂不可用时为 null。" } } }, "ImageErrorDetail": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "type": { "type": "string" } } }, "RequestID": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" }, "ErrorEnvelope": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/ErrorBody" } } }, "ActivityList": { "type": "object", "required": [ "data", "has_more" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityItem" } }, "cursor": { "type": "string", "description": "传入下一次请求的游标；当 `has_more=false` 时不返回。" }, "has_more": { "type": "boolean" } } }, "ActivityItem": { "type": "object", "required": [ "search_id", "product", "engine", "status", "cache_hit", "created_at" ], "additionalProperties": false, "properties": { "search_id": { "type": "string" }, "request_id": { "type": "string", "description": "联系支持团队时需提供的请求 ID。" }, "api_key_id": { "type": "string", "description": "原始搜索请求使用的 API 密钥 ID。" }, "product": { "type": "string" }, "engine": { "type": "string" }, "status": { "type": "string", "enum": [ "Queued", "Processing", "Success", "Error" ] }, "cache_hit": { "type": "boolean", "description": "该搜索是否符合零积分缓存响应条件。" }, "credits_used": { "type": "integer", "format": "int64", "description": "该搜索消耗的积分；在状态变为 `Success` 或 `Error` 前不返回。" }, "q": { "type": "string", "description": "搜索查询词（如有）。" }, "search_parameters": { "type": "object", "additionalProperties": true, "description": "可在其他请求中复用的搜索参数。" }, "location_requested": { "type": "string" }, "location_used": { "type": "string" }, "google_url": { "type": "string", "format": "uri" }, "error_code": { "type": "string", "description": "搜索失败时返回的错误代码。", "const": "search_failed" }, "error_message": { "type": "string", "description": "搜索失败时返回的错误信息。", "const": "Search request failed" }, "json_endpoint": { "type": "string", "format": "uri", "description": "JSON 结果文件，搜索达到 `Success` 或 `Error` 状态后可用。" }, "raw_html_file": { "type": "string", "format": "uri", "description": "HTML 结果文件，搜索结束且文件可用时返回。" }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" } } }, "GoogleLocations": { "type": "object", "required": [ "locations" ], "additionalProperties": false, "properties": { "locations": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/GoogleLocation" } } } }, "GoogleSupport": { "type": "object", "required": [ "domains", "countries", "languages", "cr_countries", "lr_languages" ], "additionalProperties": false, "properties": { "domains": { "$ref": "#/components/schemas/StringList" }, "countries": { "$ref": "#/components/schemas/StringList" }, "languages": { "$ref": "#/components/schemas/StringList" }, "cr_countries": { "$ref": "#/components/schemas/StringList" }, "lr_languages": { "$ref": "#/components/schemas/StringList" } } }, "StringList": { "type": "array", "items": { "type": "string" } }, "GoogleLocation": { "type": "object", "required": [ "id", "google_id", "name", "canonical_name", "country_code", "target_type", "reach" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "google_id": { "type": "integer", "format": "int64" }, "google_parent_id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "canonical_name": { "type": "string" }, "country_code": { "type": "string" }, "target_type": { "type": "string" }, "reach": { "type": "integer", "format": "int64" }, "gps": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "number" } } } }, "SERPRequest": { "type": "object", "description": "Google SERP 请求参数。字符串字段会去除首尾空白；除非字段另有更小限制，最大为 4096 个 UTF-8 字节。", "required": [ "q" ], "additionalProperties": false, "properties": { "engine": { "type": "string", "enum": [ "google" ], "maxLength": 4096, "default": "google" }, "q": { "type": "string", "minLength": 1, "maxLength": 4096, "pattern": "\\S", "description": "Google 搜索查询词，支持 site:、inurl:、intitle: 等高级运算符。" }, "as_dt": { "type": [ "string", "null" ], "maxLength": 4096, "description": "与 as_sitesearch 配合使用，用于包含或排除网站的 Google 高级搜索参数。" }, "as_epq": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google 高级搜索中的精确短语查询。" }, "as_eq": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google 高级搜索中要排除的查询词。" }, "as_lq": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google 高级搜索中的链接页面查询 URL。" }, "as_nlo": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google 高级搜索数值范围的下限。" }, "as_nhi": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google 高级搜索数值范围的上限。" }, "as_oq": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google 高级搜索中的可选查询词。" }, "as_q": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google 高级搜索中的附加查询词。" }, "as_qdr": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google 高级搜索的快捷日期范围，例如 d10、w2、m1 或 y。" }, "as_rq": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google 高级搜索中的相关页面查询 URL。" }, "as_sitesearch": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google 高级搜索中要限制或排除的网站。" }, "location": { "type": [ "string", "null" ], "maxLength": 4096, "description": "GET /v1/serp/locations 返回的 Google 搜索位置名称或 ID；不能与 uule 同时使用。" }, "google_domain": { "type": "string", "default": "google.com", "maxLength": 4096, "pattern": "^[Gg][Oo][Oo][Gg][Ll][Ee](?:\\.[Cc][Oo][Mm]|\\.[A-Za-z]{2}|\\.(?:[Cc][Oo][Mm]|[Cc][Oo])\\.[A-Za-z]{2})$", "description": "不含协议和路径的 Google 搜索域名，例如 google.com、google.de、google.co.jp 或 google.com.br。输入不区分大小写，会转为小写并按支持列表校验。" }, "gl": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Za-z]{2}$", "default": "us", "description": "两位 Google 国家或地区代码。输入不区分大小写，会转为小写并按支持列表校验。" }, "hl": { "type": "string", "minLength": 2, "maxLength": 32, "pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$", "default": "en", "description": "Google 界面语言代码，例如 en、ja、pt-br 或 zh-cn。输入会转为小写并按支持列表校验。" }, "uule": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google 编码位置；不能与 location 同时使用。" }, "lat": { "oneOf": [ { "type": "number", "minimum": -90, "maximum": 90 }, { "type": "string", "pattern": "^-?(?:\\d+|\\d*\\.\\d+)(?:[eE][+-]?\\d+)?$" }, { "type": "null" } ], "description": "用于 Google GPS 定位的纬度。必须与 lon 同时使用，且不能与 location 或 uule 同时使用。" }, "lon": { "oneOf": [ { "type": "number", "minimum": -180, "maximum": 180 }, { "type": "string", "pattern": "^-?(?:\\d+|\\d*\\.\\d+)(?:[eE][+-]?\\d+)?$" }, { "type": "null" } ], "description": "用于 Google GPS 定位的经度。必须与 lat 同时使用，且不能与 location 或 uule 同时使用。" }, "radius": { "oneOf": [ { "type": "number", "minimum": 1 }, { "type": "string", "pattern": "^(?:\\d+|\\d*\\.\\d+)(?:[eE][+-]?\\d+)?$" }, { "type": "null" } ], "description": "位置或 GPS 定位的搜索半径。桌面设备最大为 199，平板或移动设备最大为 1000；不能与 uule 同时使用。" }, "ludocid": { "type": [ "string", "null" ], "maxLength": 4096, "description": "地点结果的 Google CID。" }, "lsig": { "type": [ "string", "null" ], "maxLength": 4096, "description": "部分本地结果和知识图谱视图使用的 Google lsig 值。" }, "kgmid": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google 知识图谱实体 ID。" }, "si": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google 加密或缓存搜索参数令牌。" }, "ibp": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google 布局或展开参数。" }, "uds": { "type": [ "string", "null" ], "maxLength": 4096, "description": "SERP 筛选链接返回的 Google 筛选令牌。" }, "cr": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google 国家或地区限制筛选器。使用一个或多个以 `|` 分隔的 countryXX 令牌，例如 `countryUS|countryJP`。" }, "lr": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google 语言限制筛选器。使用一个或多个以 `|` 分隔的 lang_xx 令牌，例如 `lang_en|lang_zh-CN`。" }, "tbs": { "type": [ "string", "null" ], "maxLength": 4096 }, "tbm": { "type": [ "string", "null" ], "enum": [ "isch", "lcl", "vid", "nws", "shop", "pts", null ], "maxLength": 4096, "description": "支持的 Google 搜索类型；普通 Google 搜索请省略该参数。" }, "safe": { "type": "string", "enum": [ "off", "active" ], "maxLength": 4096, "default": "off" }, "nfpr": { "type": "boolean", "default": false }, "filter": { "type": "boolean", "default": true }, "start": { "type": "integer", "minimum": 0, "default": 0 }, "device": { "type": "string", "enum": [ "desktop", "tablet", "mobile" ], "maxLength": 4096, "default": "desktop" }, "async": { "type": "boolean", "default": false, "description": "为 false 时，API 等待搜索结果，也可能返回可轮询的处理中响应；为 true 时，API 立即返回可轮询的搜索响应。" }, "no_cache": { "type": "boolean", "default": false }, "webhook": { "$ref": "#/components/schemas/WebhookConfig" } } }, "TwitterRequest": { "type": "object", "description": "获取一页 Twitter 用户公开时间线的参数；必须且只能提供一个用户标识。", "additionalProperties": false, "oneOf": [ { "required": [ "username" ], "not": { "required": [ "user_id" ] } }, { "required": [ "user_id" ], "not": { "required": [ "username" ] } } ], "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 51, "pattern": "^@?[A-Za-z0-9_]+$", "description": "Twitter 用户名，可带或不带前导 `@`。" }, "user_id": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[0-9]+$", "description": "数字格式的 Twitter 用户 ID。" }, "max_results": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "本页最多返回的帖子数量。" }, "cursor": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "上一次请求返回的不透明 `next_cursor` 值。" }, "async": { "type": "boolean", "default": false, "description": "为 false 时，API 等待搜索结果，也可能返回可轮询的处理中响应；为 true 时，API 立即返回可轮询的搜索响应。" }, "webhook": { "$ref": "#/components/schemas/TwitterWebhookConfig" } } }, "WebhookConfig": { "type": "object", "required": [ "url" ], "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "使用公开主机名且不含用户名或密码的 HTTPS Webhook URL。不接受 localhost、私有 IP、特殊用途 IP 范围及 Sukidata 系统请求头覆盖；不会跟随重定向。" }, "headers": { "type": "object", "description": "可选的自定义请求头。名称必须是有效的 HTTP 请求头字段名，系统会将其规范化并拒绝不区分大小写的重复项；值不能包含多行，且 x-sukidata- 前缀为保留项。", "additionalProperties": { "type": "string" } }, "events": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "serp.search.queued", "serp.search.processing", "serp.search.completed", "serp.search.failed" ] }, "default": [ "serp.search.completed", "serp.search.failed" ] } } }, "TwitterWebhookConfig": { "type": "object", "required": [ "url" ], "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "使用公开主机名且不含用户名或密码的 HTTPS Webhook URL。不接受 localhost、私有 IP、特殊用途 IP 范围及 Sukidata 系统请求头覆盖；不会跟随重定向。" }, "headers": { "type": "object", "description": "可选的自定义请求头。名称必须是有效的 HTTP 请求头字段名，系统会将其规范化并拒绝不区分大小写的重复项；值不能包含多行，且 x-sukidata- 前缀为保留项。", "additionalProperties": { "type": "string" } }, "events": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "twitter.search.queued", "twitter.search.processing", "twitter.search.completed", "twitter.search.failed" ] }, "default": [ "twitter.search.completed", "twitter.search.failed" ] } } }, "WebhookPayload": { "type": "object", "required": [ "id", "object", "type", "api_version", "created_at", "data" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Webhook 通知或事件 ID，与 `X-Sukidata-Delivery` 一致。" }, "object": { "type": "string", "const": "event" }, "type": { "type": "string", "enum": [ "serp.search.queued", "serp.search.processing", "serp.search.completed", "serp.search.failed" ] }, "api_version": { "type": "string", "const": "v1" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/WebhookData" } } }, "WebhookData": { "type": "object", "required": [ "object" ], "additionalProperties": false, "properties": { "object": { "$ref": "#/components/schemas/WebhookSearchObject" } } }, "WebhookSearchObject": { "type": "object", "required": [ "id", "object", "endpoint", "url", "search_metadata", "search_parameters", "usage" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "search" }, "endpoint": { "type": "string", "const": "/v1/serp" }, "url": { "type": "string", "format": "uri", "description": "用于获取搜索状态或结果的已认证 API URL。" }, "search_metadata": { "$ref": "#/components/schemas/SearchMetadata" }, "search_parameters": { "$ref": "#/components/schemas/SearchParameters" }, "search_information": { "$ref": "#/components/schemas/SERPSearchInformation" }, "organic_results": { "type": "array", "items": { "$ref": "#/components/schemas/SERPOrganicResult" } }, "usage": { "$ref": "#/components/schemas/WebhookUsageFields" }, "error": { "$ref": "#/components/schemas/ErrorDetail" } } }, "SearchMetadata": { "type": "object", "required": [ "id", "status", "created_at", "total_time_taken" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "Queued", "Processing", "Success", "Error" ] }, "json_endpoint": { "type": "string", "format": "uri", "description": "该搜索的 JSON 快照 URL。搜索状态变为 `Success` 或 `Error` 后可用，并保留一个月。URL 无需 API 认证，请勿公开。" }, "raw_html_file": { "type": "string", "format": "uri", "description": "该搜索的 HTML 快照 URL（如有）。文件保留一个月且无需 API 认证，请勿公开。" }, "google_url": { "type": "string", "format": "uri", "description": "与该结果对应的 Google 搜索 URL。" }, "created_at": { "type": "string", "format": "date-time", "description": "搜索创建时间。" }, "processed_at": { "type": "string", "format": "date-time", "description": "搜索结束时间。" }, "total_time_taken": { "type": "number", "minimum": 0, "description": "搜索耗时，单位为秒，最多保留两位小数。Google 页面显示的 SERP 耗时（如有）位于 `search_information.time_taken_displayed`。" } } }, "WebhookUsageFields": { "type": "object", "required": [ "cache_hit" ], "additionalProperties": false, "properties": { "cache_hit": { "type": "boolean", "description": "该搜索是否符合零积分缓存响应条件。" }, "credits_used": { "type": "integer", "format": "int64", "description": "该搜索消耗的积分。" } } }, "ErrorDetail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "const": "search_failed" }, "message": { "type": "string", "const": "Search request failed" } } }, "SearchParameters": { "type": "object", "required": [ "engine", "q", "google_domain", "gl", "hl", "device" ], "additionalProperties": false, "properties": { "engine": { "type": "string", "const": "google", "maxLength": 4096 }, "q": { "type": "string", "minLength": 1, "maxLength": 4096, "pattern": "\\S" }, "location_requested": { "type": "string", "maxLength": 4096, "description": "请求提供 `location` 时，调用方传入的原始可读位置。" }, "location_used": { "type": "string", "maxLength": 4096, "description": "请求提供 `location` 时，匹配到的 Google 位置。" }, "as_dt": { "type": [ "string", "null" ], "maxLength": 4096 }, "as_epq": { "type": [ "string", "null" ], "maxLength": 4096 }, "as_eq": { "type": [ "string", "null" ], "maxLength": 4096 }, "as_lq": { "type": [ "string", "null" ], "maxLength": 4096 }, "as_nlo": { "type": [ "string", "null" ], "maxLength": 4096 }, "as_nhi": { "type": [ "string", "null" ], "maxLength": 4096 }, "as_oq": { "type": [ "string", "null" ], "maxLength": 4096 }, "as_q": { "type": [ "string", "null" ], "maxLength": 4096 }, "as_qdr": { "type": [ "string", "null" ], "maxLength": 4096 }, "as_rq": { "type": [ "string", "null" ], "maxLength": 4096 }, "as_sitesearch": { "type": [ "string", "null" ], "maxLength": 4096 }, "google_domain": { "type": "string", "maxLength": 4096, "pattern": "^google(?:\\.com|\\.[a-z]{2}|\\.(?:com|co)\\.[a-z]{2})$" }, "gl": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[a-z]{2}$" }, "hl": { "type": "string", "minLength": 2, "maxLength": 32, "pattern": "^[a-z]{2,3}(?:-[a-z0-9]{2,8})*$" }, "uule": { "type": [ "string", "null" ], "maxLength": 4096 }, "ludocid": { "type": [ "string", "null" ], "maxLength": 4096 }, "lsig": { "type": [ "string", "null" ], "maxLength": 4096 }, "kgmid": { "type": [ "string", "null" ], "maxLength": 4096 }, "si": { "type": [ "string", "null" ], "maxLength": 4096 }, "ibp": { "type": [ "string", "null" ], "maxLength": 4096 }, "uds": { "type": [ "string", "null" ], "maxLength": 4096 }, "cr": { "type": [ "string", "null" ], "maxLength": 4096 }, "lr": { "type": [ "string", "null" ], "maxLength": 4096 }, "tbs": { "type": [ "string", "null" ], "maxLength": 4096 }, "tbm": { "type": [ "string", "null" ], "maxLength": 4096 }, "safe": { "type": "string", "enum": [ "off", "active" ], "maxLength": 4096 }, "nfpr": { "type": "boolean" }, "filter": { "type": "boolean" }, "start": { "type": "integer", "minimum": 0 }, "device": { "type": "string", "enum": [ "desktop", "tablet", "mobile" ], "maxLength": 4096 } } }, "SERPSearchEnvelope": { "type": "object", "required": [ "search_metadata", "search_parameters" ], "additionalProperties": false, "properties": { "search_metadata": { "$ref": "#/components/schemas/SearchMetadata" }, "search_parameters": { "$ref": "#/components/schemas/SearchParameters" } } }, "SERPEnvelope": { "oneOf": [ { "$ref": "#/components/schemas/SERPSearchEnvelope" }, { "$ref": "#/components/schemas/SERPCompletedResultEnvelope" }, { "$ref": "#/components/schemas/SERPFailedResultEnvelope" } ] }, "SERPCompletedResultEnvelope": { "type": "object", "required": [ "search_metadata", "search_parameters", "search_information" ], "additionalProperties": true, "properties": { "search_metadata": { "$ref": "#/components/schemas/SearchMetadata" }, "search_parameters": { "$ref": "#/components/schemas/SearchParameters" }, "search_information": { "$ref": "#/components/schemas/SERPSearchInformation" }, "organic_results": { "type": "array", "items": { "$ref": "#/components/schemas/SERPOrganicResult" } }, "ads": { "type": "array", "items": { "$ref": "#/components/schemas/SERPLinkedResult" } }, "answer_box": { "$ref": "#/components/schemas/SERPAnswerBox" }, "ai_overview": { "$ref": "#/components/schemas/SERPAIOverview" }, "knowledge_graph": { "$ref": "#/components/schemas/SERPKnowledgeGraph" }, "local_results": { "$ref": "#/components/schemas/SERPLocalResults" }, "top_stories": { "type": "array", "items": { "$ref": "#/components/schemas/SERPLinkedResult" } }, "images_results": { "type": "array", "items": { "$ref": "#/components/schemas/SERPImageResult" } }, "videos_results": { "type": "array", "items": { "$ref": "#/components/schemas/SERPLinkedResult" } }, "shopping_results": { "type": "array", "items": { "$ref": "#/components/schemas/SERPShoppingResult" } }, "related_questions": { "type": "array", "description": "People Also Ask 及相关 AI Overview 结果（如有）。", "items": { "$ref": "#/components/schemas/SERPRelatedQuestion" } }, "related_searches": { "type": "array", "items": { "$ref": "#/components/schemas/SERPRelatedSearch" } }, "pagination": { "$ref": "#/components/schemas/SERPPagination" } } }, "SERPFailedResultEnvelope": { "type": "object", "required": [ "search_metadata", "search_parameters", "error" ], "additionalProperties": false, "properties": { "search_metadata": { "$ref": "#/components/schemas/SearchMetadata" }, "search_parameters": { "$ref": "#/components/schemas/SearchParameters" }, "error": { "$ref": "#/components/schemas/ErrorDetail" } } }, "SERPSearchInformation": { "type": "object", "description": "来自 Google 结果页和请求的搜索信息。", "required": [ "query_displayed" ], "additionalProperties": true, "properties": { "query_displayed": { "type": "string", "minLength": 1 }, "total_results": { "type": "integer", "minimum": 0 }, "time_taken_displayed": { "type": "number", "minimum": 0, "description": "Google 在 SERP 页面显示的耗时（如有），单位为秒；该值与 `search_metadata.total_time_taken` 相互独立。" } } }, "SERPOrganicResult": { "type": "object", "description": "结构化 Google 自然搜索结果。", "required": [ "position", "title", "link", "snippet" ], "additionalProperties": true, "properties": { "position": { "type": "integer", "minimum": 1, "description": "从 1 开始的 SERP 结果排名。项目必须按数组顺序严格递增，且不能重复。" }, "title": { "type": "string", "minLength": 1 }, "link": { "type": "string", "format": "uri", "description": "最终 HTTP(S) 目标 URL。" }, "displayed_link": { "type": "string", "description": "Google 显示的 URL 文本（如有）；否则使用结果主机名。" }, "source": { "type": "string", "minLength": 1, "description": "Google 显示的来源标签（如有）；否则使用结果主机名。" }, "snippet": { "type": "string", "description": "SERP 提供的摘要；Google 未提供摘要时允许为空字符串。" }, "snippet_highlighted_words": { "type": "array", "items": { "type": "string" } }, "favicon": { "type": "string", "description": "网站图标 URL（如有），不能是 data URL。" }, "date": { "type": "string" }, "sitelinks": { "type": "object", "additionalProperties": true }, "about_this_result": { "type": "object", "additionalProperties": true }, "about_page_link": { "type": "string", "format": "uri" } } }, "SERPLinkedResult": { "type": "object", "description": "解析后的带链接 SERP 富媒体卡片，用于广告、焦点新闻和视频。", "required": [ "position", "title", "link" ], "additionalProperties": true, "properties": { "position": { "type": "integer", "minimum": 1 }, "title": { "type": "string", "minLength": 1 }, "link": { "type": "string", "format": "uri" }, "source": { "type": "string" }, "snippet": { "type": "string" }, "date": { "type": "string" } } }, "SERPImageResult": { "type": "object", "required": [ "position", "title" ], "additionalProperties": true, "properties": { "position": { "type": "integer", "minimum": 1 }, "title": { "type": "string", "minLength": 1 }, "link": { "type": "string", "format": "uri" }, "thumbnail": { "type": "string", "format": "uri" } } }, "SERPShoppingResult": { "type": "object", "required": [ "position", "title" ], "additionalProperties": true, "properties": { "position": { "type": "integer", "minimum": 1 }, "title": { "type": "string", "minLength": 1 }, "link": { "type": "string", "format": "uri" }, "price": { "type": "string" }, "source": { "type": "string" }, "thumbnail": { "type": "string", "format": "uri" } } }, "SERPAIOverview": { "type": "object", "description": "Google AI Overview 内容（如有）。", "additionalProperties": true, "properties": { "status": { "type": "string", "enum": [ "success", "unavailable", "fetch_failed" ] }, "page_token": { "type": "string", "description": "Google AI Overview 页面令牌（如有）。" }, "message": { "type": "string", "description": "无法返回 Overview 时的可用性说明。" }, "error": { "type": "string", "description": "无法获取 Overview 内容时的失败原因。" }, "text_blocks": { "type": "array", "items": { "$ref": "#/components/schemas/SERPAIOverviewTextBlock" } }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/SERPAIOverviewReference" } } } }, "SERPAIOverviewTextBlock": { "type": "object", "required": [ "type", "snippet" ], "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "heading", "paragraph", "list_item" ] }, "snippet": { "type": "string", "minLength": 1 } } }, "SERPAIOverviewReference": { "type": "object", "required": [ "index", "title", "link", "source" ], "additionalProperties": true, "properties": { "index": { "type": "integer", "minimum": 1 }, "title": { "type": "string", "minLength": 1 }, "link": { "type": "string", "format": "uri" }, "source": { "type": "string", "minLength": 1 }, "snippet": { "type": "string" } } }, "SERPRelatedQuestion": { "type": "object", "required": [ "question" ], "additionalProperties": true, "properties": { "question": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "ai_overview", "featured_snippet" ] }, "page_token": { "type": "string" }, "next_page_token": { "type": "string" }, "link": { "type": "string", "format": "uri" }, "displayed_link": { "type": "string" }, "title": { "type": "string" }, "snippet": { "type": "string" }, "date": { "type": "string" }, "source_logo": { "type": "string", "format": "uri" } } }, "SERPRelatedSearch": { "type": "object", "required": [ "query" ], "additionalProperties": true, "properties": { "query": { "type": "string", "minLength": 1 }, "link": { "type": "string", "format": "uri" } } }, "SERPLocalResults": { "type": "object", "additionalProperties": true, "properties": { "places": { "type": "array", "items": { "$ref": "#/components/schemas/SERPLocalPlace" } }, "more_locations_link": { "type": "string", "format": "uri" }, "map": { "type": "object", "additionalProperties": true, "properties": { "image": { "type": "string", "format": "uri" }, "link": { "type": "string", "format": "uri" } } } } }, "SERPLocalPlace": { "type": "object", "required": [ "position", "title" ], "additionalProperties": true, "properties": { "position": { "type": "integer", "minimum": 1 }, "title": { "type": "string", "minLength": 1 }, "place_id": { "type": "string" }, "link": { "type": "string", "format": "uri" }, "rating": { "type": "number" }, "reviews": { "type": "integer", "minimum": 0 }, "type": { "type": "string" }, "address": { "type": "string" } } }, "SERPAnswerBox": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string" }, "answer": { "type": "string" }, "title": { "type": "string" }, "link": { "type": "string", "format": "uri" }, "displayed_link": { "type": "string" }, "source": { "type": "string" } } }, "SERPKnowledgeGraph": { "type": "object", "additionalProperties": true, "properties": { "title": { "type": "string" }, "type": { "type": "string" }, "description": { "type": "string" }, "source": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": "string" }, "link": { "type": "string", "format": "uri" } } } } }, "SERPPagination": { "type": "object", "additionalProperties": true, "properties": { "next": { "type": "string", "format": "uri" } } }, "TwitterSearchParameters": { "type": "object", "required": [ "engine", "max_results" ], "additionalProperties": false, "oneOf": [ { "required": [ "username" ], "not": { "required": [ "user_id" ] } }, { "required": [ "user_id" ], "not": { "required": [ "username" ] } } ], "properties": { "engine": { "type": "string", "const": "twitter" }, "username": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[A-Za-z0-9_]+$" }, "user_id": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[0-9]+$" }, "max_results": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": "string", "minLength": 1, "maxLength": 8192 } } }, "TwitterSearchEnvelope": { "type": "object", "required": [ "search_metadata", "search_parameters" ], "additionalProperties": false, "properties": { "search_metadata": { "$ref": "#/components/schemas/SearchMetadata" }, "search_parameters": { "$ref": "#/components/schemas/TwitterSearchParameters" } } }, "TwitterEnvelope": { "oneOf": [ { "$ref": "#/components/schemas/TwitterSearchEnvelope" }, { "$ref": "#/components/schemas/TwitterCompletedResultEnvelope" }, { "$ref": "#/components/schemas/TwitterFailedResultEnvelope" } ] }, "TwitterCompletedResultEnvelope": { "type": "object", "required": [ "search_metadata", "search_parameters", "user", "tweets" ], "additionalProperties": false, "properties": { "search_metadata": { "$ref": "#/components/schemas/SearchMetadata" }, "search_parameters": { "$ref": "#/components/schemas/TwitterSearchParameters" }, "user": { "$ref": "#/components/schemas/TwitterUser" }, "tweets": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/TwitterTweet" } }, "next_cursor": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "下一页的不透明游标；没有下一页时不返回。" } } }, "TwitterFailedResultEnvelope": { "type": "object", "required": [ "search_metadata", "search_parameters", "error" ], "additionalProperties": false, "properties": { "search_metadata": { "$ref": "#/components/schemas/SearchMetadata" }, "search_parameters": { "$ref": "#/components/schemas/TwitterSearchParameters" }, "error": { "$ref": "#/components/schemas/ErrorDetail" } } }, "TwitterUser": { "type": "object", "required": [ "id" ], "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "username": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string" }, "description": { "type": "string" }, "profile_image_url": { "type": "string", "format": "uri" }, "verified": { "type": "boolean" }, "followers_count": { "type": "integer", "minimum": 0 }, "following_count": { "type": "integer", "minimum": 0 }, "tweet_count": { "type": "integer", "minimum": 0 } } }, "TwitterTweet": { "type": "object", "required": [ "id", "text" ], "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "text": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "帖子发布时间（UTC），有数据时返回。" }, "language": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "author": { "$ref": "#/components/schemas/TwitterUser" }, "metrics": { "$ref": "#/components/schemas/TwitterMetrics" }, "conversation_id": { "type": "string" } } }, "TwitterMetrics": { "type": "object", "additionalProperties": false, "properties": { "like_count": { "type": "integer", "minimum": 0 }, "retweet_count": { "type": "integer", "minimum": 0 }, "reply_count": { "type": "integer", "minimum": 0 }, "quote_count": { "type": "integer", "minimum": 0 }, "bookmark_count": { "type": "integer", "minimum": 0 }, "view_count": { "type": "integer", "minimum": 0 } } }, "TwitterWebhookPayload": { "type": "object", "required": [ "id", "object", "type", "api_version", "created_at", "data" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Webhook 通知或事件 ID，与 `X-Sukidata-Delivery` 一致。" }, "object": { "type": "string", "const": "event" }, "type": { "type": "string", "enum": [ "twitter.search.queued", "twitter.search.processing", "twitter.search.completed", "twitter.search.failed" ] }, "api_version": { "type": "string", "const": "v1" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/TwitterWebhookData" } } }, "TwitterWebhookData": { "type": "object", "required": [ "object" ], "additionalProperties": false, "properties": { "object": { "$ref": "#/components/schemas/TwitterWebhookSearchObject" } } }, "TwitterWebhookSearchObject": { "type": "object", "required": [ "id", "object", "endpoint", "url", "search_metadata", "search_parameters", "usage" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "search" }, "endpoint": { "type": "string", "const": "/v1/twitter" }, "url": { "type": "string", "format": "uri", "description": "用于获取搜索状态或结果的已认证 API URL。" }, "search_metadata": { "$ref": "#/components/schemas/SearchMetadata" }, "search_parameters": { "$ref": "#/components/schemas/TwitterSearchParameters" }, "user": { "$ref": "#/components/schemas/TwitterUser" }, "tweets": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/TwitterTweet" } }, "next_cursor": { "type": "string", "minLength": 1, "maxLength": 8192 }, "usage": { "$ref": "#/components/schemas/WebhookUsageFields" }, "error": { "$ref": "#/components/schemas/ErrorDetail" } } }, "ErrorBody": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "maxLength": 80, "pattern": "^[a-z][a-z0-9_]*$" }, "message": { "type": "string", "minLength": 1, "maxLength": 240 } } } } } }