{"openapi":"3.1.0","info":{"title":"TokTesk Video API","version":"1.1.0","description":"TokTesk 统一视频生成 API。可用模型、时长、分辨率与价格以 /v1/catalog 和 /v1/pricing 的实时返回为准，随平台渠道开放/关闭自动更新。\n\n每个响应都带 X-Request-Id；每个 Key 每分钟最多 300 次请求、30 次创建任务（X-RateLimit-* 响应头）。回调签名：X-TokTesk-Signature: t=<时间戳>,v1=HMAC_SHA256(secret, t + \".\" + body)，secret = HMAC_SHA256(API Key, \"toktesk-webhook\") 的十六进制。"},"servers":[{"url":"https://toktesk.com"}],"security":[{"bearerAuth":[]}],"paths":{"/v1/catalog":{"get":{"summary":"获取模型目录","description":"返回当前开放的模型、可选时长、画面比例与参考图上限。","security":[],"responses":{"200":{"description":"模型能力列表"}}}},"/v1/pricing":{"get":{"summary":"获取积分价格","description":"返回每个模型、每个时长的积分价格。","security":[],"responses":{"200":{"description":"各模型、各时长的积分价格"}}}},"/v1/balance":{"get":{"summary":"查询积分余额与流水","responses":{"200":{"description":"账户积分"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/files":{"post":{"summary":"上传参考图片","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["image_b64"],"properties":{"image_b64":{"type":"string","description":"PNG、JPEG 或 WebP 的 base64 或 data URL"}},"additionalProperties":false}}}},"responses":{"201":{"description":"返回 image_id"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/videos":{"post":{"summary":"创建视频生成任务","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]{8,128}$"},"description":"同一业务请求重试时保持不变"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVideo"}}}},"responses":{"200":{"description":"命中幂等请求，返回已存在的任务"},"202":{"description":"任务已创建","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoTask"}}}},"400":{"description":"参数无效或缺少 Idempotency-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"请求 IP 不在该 Key 的白名单内（IP_NOT_ALLOWED）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"相同 Idempotency-Key 用于了不同参数","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"超过每日额度 / 并发上限，或调用频率超限（RATE_LIMITED，见 Retry-After 响应头）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/videos/{id}":{"get":{"summary":"查询并刷新任务状态","parameters":[{"$ref":"#/components/parameters/TaskId"}],"responses":{"200":{"description":"任务状态","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoTask"}}}},"404":{"description":"任务不存在","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/videos/{id}/signed_url":{"get":{"summary":"获取 10 分钟有效的原片下载地址","parameters":[{"$ref":"#/components/parameters/TaskId"}],"responses":{"200":{"description":"限时签名地址"},"409":{"description":"任务尚未完成","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/test":{"post":{"summary":"向回调地址发送一条测试通知","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["callback_url"],"properties":{"callback_url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"投递结果","content":{"application/json":{"schema":{"type":"object","properties":{"delivered":{"type":"boolean"},"status":{"type":["integer","null"]},"ms":{"type":"integer"},"error":{"type":["string","null"]}}}}}},"400":{"description":"地址无效（必须是公网 https）"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/webhooks/deliveries":{"get":{"summary":"最近 50 条回调投递记录","parameters":[{"name":"task_id","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"投递记录"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"TokTesk API Key"}},"parameters":{"TaskId":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}},"schemas":{"CreateVideo":{"type":"object","required":["prompt","model","duration"],"additionalProperties":false,"properties":{"prompt":{"type":"string","maxLength":6000,"description":"最多 6000 字"},"model":{"type":"string","description":"以 /v1/catalog 实时返回为准，随平台渠道开放/关闭自动更新。当前可用：zb-sd25-720（Seedance 2.5 按秒 L 720P）；zb-wan30p-720（Wan 3.0 720P · 15/30 秒 官转通道）；zb-wan30p-1080（Wan 3.0 1080P · 15/30 秒 （官转））；zb-mmh3-720（MiniMax H3 L 720P）；zb-mmh3-2k（MiniMax H3 L 2K）；hs-bb25-720（Seedance 2.5 全能参考 720P）；zb-muse-720（Muse 视频 L 720P · 固定 10 秒）；zb-gemini-720（Gemini Omni Flash L 720P · 首帧）","enum":["zb-sd25-720","zb-wan30p-720","zb-wan30p-1080","zb-mmh3-720","zb-mmh3-2k","hs-bb25-720","zb-muse-720","zb-gemini-720"]},"duration":{"type":"integer","minimum":3,"maximum":30,"description":"秒。每个模型可选的时长见 /v1/catalog"},"ratio":{"type":"string","enum":["1:1","3:4","4:3","9:16","16:9","21:9"],"default":"9:16"},"resolution":{"type":"string","description":"每个模型的分辨率固定，见 /v1/catalog 的 resolutions，可不传。","enum":["720p","1080p","2k"]},"camera_movement":{"type":"string","enum":["auto","fixed"]},"image_ids":{"type":"array","maxItems":30,"items":{"type":"string"},"description":"先用 /v1/files 上传得到的 image_id；数量上限见 /v1/catalog 的 maxImages"},"callback_url":{"type":"string","format":"uri","maxLength":500,"description":"可选。任务结束（succeeded / failed / cancelled）后，平台向该 https 地址 POST 签名通知，失败自动重试 5 次。"}}},"VideoTask":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","running","succeeded","failed"]},"model":{"type":"string"},"model_name":{"type":"string"},"cost_credits":{"type":"integer","description":"本次扣除的积分"},"error":{"type":["object","null"]}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string","description":"请求编号，联系技术支持时提供"}}}}}},"responses":{"Unauthorized":{"description":"API Key 无效或已停用"}}}}