> ## 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 キー・channel・status などを保存します。
3. 未完了タスクは 10 秒間隔で Ark をポーリングします。
4. 課金は成功結果の `usage.completion_tokens` を読み取ります。

> レスポンスの `video_url` は Ark の署名付き一時 URL です。有効期限は 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 キー、channel、status を保存し、バックグラウンドのポーリングを開始します。

## タスク照会

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

ゲートウェイ DB から結果を返します。生成中は status、完了後は 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 相当として計上され、Ark の値を反映します。

## ステータス

* **RUNNING**：ゲートウェイが Ark をポーリング中
* **SUCCEEDED**：最終結果を取得済み。以降は完全結果を返します
* **NOT\_FOUND**：ゲートウェイにタスク ID が存在しません（無効またはクリーンアップ済み）

## エラーと HTTP

* **401/403**：キー不正、組織無効、残高不足など
* **200 + body**：照会エンドポイントは常に 200。状態は JSON で表現
* **5xx**：内部エラーまたは Ark 障害。再試行を検討

## 運用のコツ

* 5〜10 秒間隔でポーリング（ゲートウェイは 10 秒）
* レスポンスの `x-request-id` を残す
* `video_url` が期限切れなら新規タスクで再取得（現状リフレッシュ不可）
* 同一内容の重複作成は避ける（冪等キー無し）