{"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","properties":{"image_b64":{"type":"string","description":"参考图片：PNG、JPEG 或 WebP 的 base64 或 data URL（单张 ≤ 5 MB），返回 image_id"},"audio_b64":{"type":"string","description":"参考音频：MP3、WAV、M4A、OGG 或 FLAC 的 base64 或 data URL（单个 ≤ 50 MB），返回 audio_id"},"video_b64":{"type":"string","description":"参考视频：MP4、MOV 或 WebM 的 base64 或 data URL（单条 ≤ 50 MB），返回 video_id"},"name":{"type":"string","maxLength":70,"description":"可选，音频 / 视频的显示名称"}},"additionalProperties":false,"oneOf":[{"required":["image_b64"]},{"required":["audio_b64"]},{"required":["video_b64"]}],"description":"每次只上传一个文件：image_b64、audio_b64、video_b64 三选一。"}}}},"responses":{"201":{"description":"图片返回 image_id；音频返回 audio_id；视频返回 video_id（同时返回 type、bytes）"},"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 实时返回为准，随平台渠道开放/关闭自动更新。当前可用：hs-sd20d（Seedance 2.0 定长版 · 5/10/15 秒）；gw-mmh3o-768（MiniMax H3 官 G 768P）；gw-mmh3o-2k（MiniMax H3 官 G 2K）；gw-sd25v3-720（Seedance 2.5 G5 V3 G 720P · 不支持参考视频）；gw-sd25fl-720（Seedance 2.5 Flash G 720P）；gw-wan3p-720（Wan 3 Prime G 720P · 素材合计≤20）；gw-wan3p-1080（Wan 3 Prime G 1080P · 素材合计≤20）；gw-sd25g21-720（Seedance 2.5 G2-1 G 720P）","enum":["hs-sd20d","gw-mmh3o-768","gw-mmh3o-2k","gw-sd25v3-720","gw-sd25fl-720","gw-wan3p-720","gw-wan3p-1080","gw-sd25g21-720"]},"duration":{"type":"integer","minimum":2,"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":["default","768p","2k","720p","1080p"]},"camera_movement":{"type":"string","enum":["auto","fixed"]},"image_ids":{"type":"array","maxItems":30,"items":{"type":"string"},"description":"先用 /v1/files 上传得到的 image_id（image_b64）；数量上限见 /v1/catalog 的 maxImages"},"callback_url":{"type":"string","format":"uri","maxLength":500,"description":"可选。任务结束（succeeded / failed / cancelled）后，平台向该 https 地址 POST 签名通知，失败自动重试 5 次。"},"audio_ids":{"type":"array","maxItems":10,"items":{"type":"string"},"description":"先用 /v1/files 上传 audio_b64 得到的 audio_id；仅支持参考音频的模型可用，数量上限见 /v1/catalog 的 maxAudios（为 0 表示不支持）"},"video_ids":{"type":"array","maxItems":10,"items":{"type":"string"},"description":"先用 /v1/files 上传 video_b64 得到的 video_id；仅支持参考视频的模型可用，数量上限见 /v1/catalog 的 maxVideos（为 0 表示不支持）"}}},"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 无效或已停用"}}}}