> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yourouter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Ark 文生视频

> 通过 YouRouter 调用 Ark 的视频生成 API。

## Base URL

`https://api.yourouter.ai`

## 鉴权

每个请求都需要带上以下任一请求头：

* `Authorization: Bearer <YOUROUTER_API_KEY>`
* `x-api-key: <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 保持一致。示例：

```bash theme={null}
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）：

```json theme={null}
{ "id": "cgt-20250906194036-2k4r4" }
```

网关会把这个 ID 与模型、组织、Ark key、channel、status 等信息一起存下来，并启动后台轮询。

## 查询任务

**Endpoint**：`GET /api/v3/contents/generations/tasks/{id}`

该接口从网关数据库中返回任务结果。如果任务仍在生成中，响应会包含当前状态；如果任务已完成，则返回 Ark 的完整结果，并注入 `id` 和 `vendor` 字段。

```bash theme={null}
curl -X GET https://api.yourouter.ai/api/v3/contents/generations/tasks/cgt-20250906194036-2k4r4 \
  -H "Authorization: Bearer $YOUROUTER_API_KEY"
```

**运行中示例**：

```json theme={null}
{ "id": "cgt-20250906194036-2k4r4", "status": "RUNNING" }
```

**完成示例**：

```json theme={null}
{
  "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 当前不支持刷新。
* 尽量避免重复提交相同内容，目前没有幂等键。