TikdekTikdek
异步交付

用状态查询与 Webhook 稳定交付视频

简单客户端使用轮询，自动化服务使用 Webhook，两者共享同一套任务生命周期。

生成 API Key阅读文档
创建带 Webhook 的任务
curl -X POST https://sora2-api.com/api/v1/video/sora-video \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A tracking shot through a quiet night market",
    "aspectRatio": "16:9",
    "webHook": "https://api.example.com/webhooks/video",
    "isPublic": false
  }'

# Your webhook receives a terminal payload:
{
  "id": "task_123",
  "status": "succeeded",
  "progress": 100,
  "results": [{ "url": "https://storage.example/video.mp4" }]
}

同一生命周期，两种交付方式

保存每个任务 ID，并只把 succeeded 与 failed 视为终态。

可预期的轮询

创建任务后调用 check-result 轮询状态与进度，无需 SSE 长连。

20 并发支持

最多同时处理 20 个视频生成任务。如需更高并发，请通过邮件联系我们。

透明可控的计费

sora-2 与 sora-2-stable 按时长计费：10s 100 积分、15s 150 积分；sora-2-pro 每次 150 积分，失败任务自动退款，便于统计成本。

推荐对接流程

Webhook 交付规则

快速返回 2xx，按任务 ID 做幂等处理，同时保留轮询作为恢复路径。

创建任务

发送 Sora 2 接口，携带提示词，并保存返回的 taskId。

跟踪进度

调用查询接口，直到状态变为 succeeded 或 failed。

分发成片

使用 result_url / result_urls 中已经上传到存储的地址向用户交付视频。

常见问题

接口如何鉴权？

在控制台创建 API Key 后，以 Authorization: Bearer YOUR_API_KEY 发送请求，可随时在控制台轮换密钥。

如何轮询获取结果？

调用创建接口后保存 taskId，每 3-5 秒调用 /api/video-generations/check-result，直到状态为 succeeded 或 failed，再使用 result_url/result_urls。

失败任务的积分如何处理？

系统会自动返还积分，并在查询结果中返回 refund_trans_no 与 credits_refunded=true，便于对账。

上线可靠的异步生成

先用轮询完成集成，再在不改变生成协议的前提下加入 Webhook。

前往 API 控制台查看价格