跳转到主要内容

​
Base URL

https://api.yourouter.ai

​
鉴权

每个请求都需要带上以下任一请求头：
  • Authorization: Bearer <YOUR_YOUROUTER_API_KEY>
  • x-api-key: <YOUR_YOUROUTER_API_KEY>
所有请求都应带上 Content-Type: application/json。 每个响应都会返回 x-request-id 头，便于追踪与排障。

​
工作方式

  1. 客户端调用网关，使用与 Ark 官方 API 相同的请求体创建任务。
  2. 网关立即返回 Ark 生成的任务 ID，并保存任务相关信息，例如组织、模型、Ark key、channel、status 等。
  3. 对于尚未完成的任务，网关会每 10 秒使用保存的 Ark API Key 轮询一次。
  4. 计费时读取成功结果中的 usage.completion_tokens。
响应中的 video_url 是 Ark 返回的带签名临时链接，有效期为 86,400 秒（24 小时），请在过期前下载视频。

​
创建任务

Endpoint：POST /api/v3/contents/generations/tasks 请求体与 Ark 官方 API 保持一致。示例： 
curl -X POST https://api.yourouter.ai/api/v3/contents/generations/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $YOUROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedance-1-0-pro-250528",
    "content": [
      {
        "type": "text",
        "text": "Drone races through obstacles at high speed for an immersive flight experience  --resolution 1080p  --duration 5 --camerafixed false --watermark true"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_i2v.png" }
      }
    ]
  }'
成功响应（创建阶段通常只返回 Ark 任务 ID）： 
{ "id": "cgt-20250906194036-2k4r4" }
网关会把这个 ID 与模型、组织、Ark key、channel、status 等信息一起存下来，并启动后台轮询。

​
查询任务

Endpoint：GET /api/v3/contents/generations/tasks/{id} 该接口从网关数据库中返回任务结果。如果任务仍在生成中，响应会包含当前状态；如果任务已完成，则返回 Ark 的完整结果，并注入 id 和 vendor 字段。 
curl -X GET https://api.yourouter.ai/api/v3/contents/generations/tasks/cgt-20250906194036-2k4r4 \
  -H "Authorization: Bearer $YOUROUTER_API_KEY"
运行中示例： 
{ "id": "cgt-20250906194036-2k4r4", "status": "RUNNING" }
完成示例： 
{
  "id": "your-00000000000000000000000000000000",
  "model": "doubao-seedance-1-0-pro-250528",
  "status": "succeeded",
  "content": {
    "video_url": "https://ark-content-generation-cn-beijing.tos-cn-beijing.volces.com/doubao-seedance-1-0-pro/....mp4?...&X-Tos-Expires=86400&..."
  },
  "usage": {
    "completion_tokens": 246840,
    "total_tokens": 246840
  },
  "created_at": 1757158837,
  "updated_at": 1757158914,
  "seed": 95409,
  "resolution": "1080p",
  "duration": 5,
  "ratio": "16:9",
  "framespersecond": 24,
  "vendor": "Ark"
}

​
计费

  • 只有当 status 为 succeeded 时才会记录 usage。
  • 成功结果中的 usage.completion_tokens 会按文本 completion usage 计费，其数值与 Ark 返回保持一致。

​
状态值

  • RUNNING：网关正在轮询 Ark。
  • SUCCEEDED：最终结果已拉取并存储，后续查询会返回完整结果。
  • NOT_FOUND：网关中没有这个任务 ID，可能任务不存在或已被清理。

​
错误与状态码

  • 401/403：API Key 缺失或无效、组织被禁用、余额不足等。
  • 200 + body：查询接口始终返回 HTTP 200，任务状态通过 JSON body 表达。
  • 5xx：内部服务错误或 Ark 不可用，建议重试。

​
使用建议

  • 每隔 5 到 10 秒轮询一次任务，网关本身每 10 秒轮询 Ark。
  • 为了排障，请保留响应中的 x-request-id。
  • 如果 video_url 已过期，需要重新创建任务获取新链接，Ark 当前不支持刷新。
  • 尽量避免重复提交相同内容，目前没有幂等键。