# Seedance 2.5 · Special — /videos/generations

4〜30秒の整数、720P、16:9または9:16。参照画像は最大30枚、参照音声は最大10本。参照動画は非対応。参照音声なしは1本$2（400クレジット）、ありは$3（600クレジット）。長さによる料金変更はありません。生成された音声は参照音声ではありません。期間限定で、継続提供は保証しません。待ち時間は混雑状況により変わります。再送せず元のタスクを照会してください。失敗時は全額返金。

**エンドポイント:** `POST https://kovapi.com/v1/videos/generations`

## クイックスタート

3 ステップで動きます：タスクを送信 → 結果を照会 → 動画のリンクを受け取る。YOUR_API_KEY をご自身のキーに置き換えれば、下のコマンドはそのまま実行できます。

**ステップ 1 · タスクを送信（すぐにタスク ID が返ります。HTTP 202）**

```
curl https://kovapi.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedance-2.5-30s", "prompt": "秋の谷あいの町を旅人が夜明けから夕暮れまで歩いていく、カメラがずっと後を追う", "duration": 25, "resolution": "720P", "size": "16:9"}'
```

レスポンス（HTTP 202）

```
{
  "id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
  "object": "video.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "seedance-2.5-30s"
}
```

**ステップ 2 · `status` が `succeeded` か `failed` になるまで、5〜10 秒ごとに照会**

```
curl https://kovapi.com/v1/videos/jobs/img_5c2e8f1a9b3d7e6f0a4c8b2d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

成功時のレスポンス

```
{
  "id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
  "object": "video.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "seedance-2.5-30s",
  "data": [
    {"url": "https://img.kovapi.com/i/8c1f0e5d2b7a49e3a6d0c4f1b9e2a7d5.mp4"}
  ],
  "usage": {"clips": 1, "model": "seedance-2.5-30s"}
}
```

**ステップ 3 · `data[0].url` が動画（MP4）のリンクです。保存期間は 15 日間なので、長く使う場合はご自身のストレージにダウンロードしてください。**

**完全なサンプル（Python：送信 → 待機 → ローカルに保存）**

```
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. タスクを送信
job = requests.post(f"{BASE}/videos/generations", headers=HEADERS, json={
    "model": "seedance-2.5-30s",
    "prompt": "秋の谷あいの町を旅人が夜明けから夕暮れまで歩いていく、カメラがずっと後を追う",
    "duration": 25,
    "resolution": "720P",
    "size": "16:9",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. 10 秒ごとに照会（最長 1 時間）
deadline = time.time() + 3600
while job["status"] not in ("succeeded", "failed") and time.time() < deadline:
    time.sleep(10)
    job = requests.get(f"{BASE}/videos/jobs/{job['id']}", headers=HEADERS).json()

# 3. 動画をダウンロード
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("seedance-2.5-30s.mp4", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
elif job["status"] == "failed":
    print("failed:", job["error"]["code"], job["error"]["message"])
else:
    print("still", job["status"], job["id"])
```

順番待ちの間は、照会結果に `queue_position`（前に並んでいるタスクの数）と `eta_seconds`（予想待ち時間）も含まれます。設定した待ち時間の上限を過ぎても、再送信はしないでください。タスクは残っているので、しばらくしてから同じタスク ID で照会を続けてください。

## 認証
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 仕様早見表

| 長さ | 4–30 秒 |
| --- | --- |
| 解像度 | 720P |
| 比率 | 16:9 / 9:16 |
| 参照画像 | 最大 30 枚 · 参照用（人物・シーン・スタイル）。フレームとしては使われません |
| 参照動画 | 非対応 |
| 参照音声 | 最大 10 本 |
| 音声 | 常に付きます。オフにはできません（`audio: false` は拒否されます） |
| 課金方法 | 1 本ごと：長さに関係なく同じ料金 |

## リクエストパラメータ

| パラメータ | 種別 | 必須 | 説明 |
| --- | --- | --- | --- |
| model | string | はい | モデル ID。ここでは seedance-2.5-30s です。 |
| prompt | string | はい | 内容、カメラ、動作を記述します。 |
| duration | integer | いいえ | 長さ（秒）。4〜30 の任意の整数で、既定は 30、つまり最長の値です。1 本ごとの課金なので、長さは価格を変えません。seconds とも書けます。 |
| resolution | string | いいえ | 720P |
| size | string | いいえ | 画面比率: 16:9 / 9:16（既定は 16:9）。aspect_ratio とも書けます。このモデルは 21:9 に対応していません。 |
| image | string | いいえ | Image-to-video: include a reference image (public URL, data: URI or base64); omit for text-to-video. |
| images | array | いいえ | 複数枚の参照画像。最大 30 枚です。上限を超えた場合は切り詰めずに拒否します。reference_images とも書けます。 |
| audio_reference | string / array | いいえ | 公開HTTPS URLまたは配列、最大10本。参照画像が1枚以上必要です。MP3/WAV/M4A、各15MB・30秒まで。参照音声ありは1本$3（600クレジット）。 |
| audio | boolean | いいえ | どの動画にも音声が付き、オフにはできません。`false` は拒否される（400）ので、指定しないでください。 |
| callback_url | string | いいえ | タスク終了時に結果を送る先。下の Webhook の項目をご覧ください。 |
| n | integer | いいえ | 1 つのタスクで生成される動画は 1 本なので、指定する必要はありません。1 より大きい値を指定しても生成されるのは 1 本ですが、送信時に n 本分の料金が確保され、余分な分はタスク終了時に戻ります。 |

## 料金

期間限定 · 1本ごとの課金

|  | クレジット / 本 | USD / 本 |
| --- | --- | --- |
| 参照音声なし | 400 | $2.00 |
| 参照音声あり | 600 | $3.00 |

4〜30秒の整数、720P、16:9または9:16。参照画像は最大30枚、参照音声は最大10本。参照動画は非対応。参照音声なしは1本$2（400クレジット）、ありは$3（600クレジット）。長さによる料金変更はありません。生成された音声は参照音声ではありません。期間限定で、継続提供は保証しません。待ち時間は混雑状況により変わります。再送せず元のタスクを照会してください。失敗時は全額返金。

## 参照素材

4〜30秒の整数、720P、16:9または9:16。参照画像は最大30枚、参照音声は最大10本。参照動画は非対応。参照音声なしは1本$2（400クレジット）、ありは$3（600クレジット）。長さによる料金変更はありません。生成された音声は参照音声ではありません。期間限定で、継続提供は保証しません。待ち時間は混雑状況により変わります。再送せず元のタスクを照会してください。失敗時は全額返金。

参照画像は最大 30 枚で、人物、シーン、スタイルを決めます。フレームとしては使われません。プロンプトでは `@Image1`、`@Image2` のように指定します。

実在の人物の顔もそのまま参照画像に使えます（隠す必要はありません）。写っている人物の肖像を使用する権利があることを必ずご確認ください。

```
{
  "model": "seedance-2.5-30s",
  "prompt": "Follow @Image1 and use @Audio1 as the soundtrack",
  "duration": 25, "resolution": "720P", "size": "16:9",
  "images": ["https://example.com/reference.png"],
  "audio_reference": ["https://example.com/reference.mp3"]
}
```

## コンテンツ要件

Seedance のタスクはすべてコンテンツ審査を通ります。対象はプロンプト、参照素材、生成された動画で、映像も音声も審査されます。審査で不合格になったタスクは `content_policy` で失敗し、課金されません。

### 審査のタイミング

送信時にプロンプトと参照素材が審査され、動画の生成後に映像と音声がもう一度審査されます。そのため不合格の結果は、送信から数秒で返ることもあれば、レンダリングの終了後に返ることもあります（30分以上かかることもあります）。`status` が `failed`、`error.code` が `content_policy` で終わったタスクは審査で不合格です。Webhook では `video.failed` イベントが届きます。

### 課金なし

不合格のタスクは課金されません。送信時に仮押さえした金額はタスク終了時に全額返金され、呼び出しログでも課金なしと表示されます。

### 音声

音声（セリフ、ナレーション、歌、効果音）はプロンプトに沿ってモデルが生成し、映像と一緒に審査されます。プロンプトに書いたセリフ、ナレーション、歌詞は読み上げられたり歌われたりします。人の声が要らない動画なら、プロンプトにセリフや歌詞を書かないでください。このモデルは毎回音声付きで出力され、オフにできません。アップロードした参照音声も審査され、著作権のある音楽を参照音声に使うと弾かれることがあります。

### よく弾かれる内容

- 性的な内容、裸、性的なほのめかし（AI で生成・合成した画像を含む）

- 流血、残虐な描写、自傷、銃撃や出血などの暴力による負傷

- 銃器、爆発物、薬物

- 未成年者を性的に扱う内容は一切不可。未成年者と酒・たばこ・薬物・危険な行為の組み合わせも弾かれます

- 政治家、芸能人、スポーツ選手、経済人など公人の容姿や声（よく似た人物を含む）

- 著作権で保護されたキャラクターや IP（ディズニーやマーベルのキャラクターなど）

- 憎悪や差別的な内容、フェイクニュース

### 長い絵コンテ台本

違反するカットが1つでもあれば動画全体が弾かれます。長い絵コンテ台本で特に起きやすく、アクションシーンの銃撃戦や出血のアップ、未成年者が飲酒や喫煙をする場面があると全体が失敗します。送信前に台本を通して読み、こうしたカットを削除するか書き直してください。

### 実在の人物

実在の人物の写真を参照に使うには、その人物の肖像を使う権利が必要です。

### 弾かれたあと

同じ内容で再送信しても再び弾かれます。問題になりそうな部分を見つけ、プロンプトを書き直すか参照素材を差し替えてから送信し直してください。

エラーコード: `content_policy` · `status: failed`

`upstream_line_unavailable`: 生成サービスが過負荷または利用可能なリソースが不足した場合、upstream_line_unavailable を返します。失敗タスクは課金されず、予約ポイントは返還されます。しばらくして再試行してください。このエラーは特定のパラメータや素材の問題を示していません。明確な時間制限、参照の読み取り失敗、審査拒否は、それぞれ duration_rejected、reference_unreadable、content_policy を返すため、対応する説明に従ってください。

## タスクの状態と返却フィールド

`GET /v1/videos/jobs/{id}` は次のステータスを返します。各フィールドの説明は [非同期タスク](https://docs.kovapi.com/ja/guide/async-jobs#fields) をご覧ください。5〜10 秒ごとに照会するか、下の Webhook で結果を受け取ってください。ポーリングは無料で、同じアカウントのキーならどれでもこのタスクを照会できます。

| ステータス | 意味 |
| --- | --- |
| queued | 順番待ち。`queue_position`（前にあるタスク数）と `eta_seconds`（予想待ち時間）が付きます。 |
| processing | 生成中。 |
| succeeded | 完了。結果は `data[0].url`、課金の内訳は `usage` にあります。 |
| failed | 失敗。理由は `error` にあり、予約したクレジットは全額返金されます。 |

- `processing` が `queued` に戻ることがあります。たとえば、混み合っているとき、完成した動画を取得し直しているとき、サービスの再起動後などです。タスクを完了できなかった場合、ゲートウェイが自動で生成し直すことがあります。何回再試行しても、課金は 1 タスクにつき 1 回だけです。

- 1 つのアカウントで同時に生成できるタスクは 50 件までで、それ以上は送信順に順番待ちになります。15 分たっても始まらないタスクは失敗となり、全額返金されます。タスクの記録は 3 日間、動画のリンクは 15 日間保存されます。

## 生成にかかる時間

4〜30秒の整数、720P、16:9または9:16。参照画像は最大30枚、参照音声は最大10本。参照動画は非対応。参照音声なしは1本$2（400クレジット）、ありは$3（600クレジット）。長さによる料金変更はありません。生成された音声は参照音声ではありません。期間限定で、継続提供は保証しません。待ち時間は混雑状況により変わります。再送せず元のタスクを照会してください。失敗時は全額返金。

## エラーと返金

送信時のエラーはすぐに HTTP 4xx / 5xx で返り、タスクは作成されず、課金もされません。受け付け後の失敗は照会エンドポイントで報告され、確保額は全額返金されます。すべてのコードは [エラーコード](https://docs.kovapi.com/ja/guide/errors) に載っています。

### 送信時に返るエラー

| HTTP | code | 原因 | 対処 |
| --- | --- | --- | --- |
| 400 | invalid_request | パラメータが不正です。たとえば、長さ・解像度・比率・参照素材の数がこのモデルの範囲外、プロンプトが長すぎる、参照画像や参照動画を読み込めない、常に音声が付くモデルに `audio: false` を指定した、などです。どれに当たるかは `message` に書かれています。 | `message` の内容に沿って直してから、もう一度送信してください。 |
| 400 | invalid_callback_url | `callback_url` が公開された http(s) のアドレスではないか、2000 文字を超えています。 | インターネットからアクセスできるアドレスを使ってください。 |
| 400 | model_not_found | モデル ID のつづりが違う・`model` がない・そのモデルをこのエンドポイントでは使えない（たとえば対話モデルで画像のエンドポイントを呼び出した）のいずれかです。 | `GET /v1/models` または [API リファレンス](https://docs.kovapi.com/ja/api) にあるモデル ID を使ってください。 |
| 401 | invalid_api_key | キーが存在しない・削除された・無効化されているか、アカウントが停止されています。 | コンソールの「API Keys」ページでキーを確認してください。 |
| 402 | insufficient_quota | このリクエストの分を確保するだけの残高がありません。ゲートウェイはまずリクエストにかかりうる最大の費用を確保するため、同時に多くの呼び出しを送ったときにも起こることがあります。 | 一度に多くの呼び出しを送った直後なら、数秒待って再試行してください。そうでなければチャージしてください。 |
| 429 | rate_limit_exceeded | このキーに設定した 1 分あたりのリクエスト数の上限を超えました（直近 60 秒で数えます）。`Retry-After` ヘッダーは付きません。 | 数秒待ってから再試行するか、コンソールでこのキーの上限を引き上げてください。 |
| 503 | model_maintenance | モデルのメンテナンス中で、リクエストを受け付けていません。その間、別のモデルが代わりに回答することもありません。 | メンテナンスが終わってから再試行してください。状況は [サービス状態](https://kovapi.com/ja/status) で確認できます。 |
| 503 | service_unavailable | 当サイト側の一時的なエラーです（参照素材の保存に失敗した場合など）。タスクは作成されておらず、課金もされていません。 | しばらくしてから再試行してください。 |

### 失敗したタスク（`status` が `failed`）

| code | 発生する場面 | 対処 |
| --- | --- | --- |
| content_policy | 動画：プロンプト、参照素材、または生成された映像や音声がコンテンツ審査を通りませんでした（音声が引っかかった場合は `param` が `audio` になります）。 Wan Standard / Prime：入力素材が審査を通過しませんでした。`error.reason` は `FaceDetectionSuspect`（実在の人物の顔の可能性）または `DataInspectionFailed`（入力コンテンツ審査不通過）です。`error.message` に理由と変更方法が示されます。失敗したタスクは課金されません。 | プロンプトを書き直すか参照素材を差し替えてから、もう一度送信してください。同じ内容のままでは再び拒否されます。 |
| duration_rejected | 動画：長さが受け付けられませんでした。多いのは、参照音声か参照動画が上限をわずかでも超えている場合です。 | 参照音声・参照動画を上限内に収まるよう短くしてから、もう一度送信してください。同じ内容のままでは再び失敗します。 |
| reference_unreadable | 動画：参照画像・動画・音声をモデルがダウンロードできませんでした。多いのは、YouTube やクラウドストレージの共有ページなどウェブページのリンクの場合です。 | ファイルを直接ダウンロードできるリンクに替えるか、Playground でファイルをアップロードしてください。同じ内容のままでは再び失敗します。 |
| invalid_video_request | 送信時にパラメータまたは参照素材が受け付けられず、生成は始まっていません。 | 長さ・画面比率・参照素材を確認して再送してください。料金は発生しません。 |
| special_failed | 生成に失敗し、動画は作られませんでした。 | 料金は発生しません。そのまま再送できます。 |
| special_unknown | 送信が受け付けられたかどうか明確な応答がありませんでした。二重生成を避けるため、再送はしていません。 | 料金は発生しません。再送できます。 |
| special_fetch | 動画は生成されましたが、ファイルの取得に繰り返し失敗しました。 | 料金は発生しません。再送してください。 |
| special_unavailable | このプランが利用できなかったか、120分以内に生成が始まりませんでした。 | 料金は発生しません。しばらくしてから再送してください。 |

判定は `message` の文面ではなく `code` で行ってください。知らない `code` の場合（または `code` がない場合）は `upstream_error` として扱ってください。たいていは再送信すれば成功します。失敗したタスクはすべて全額返金されます。

## ポーリングの代わりに Webhook を使う

送信時に `callback_url` を付けると、タスクが終わった時点で（成功・失敗とも）、照会エンドポイントが返すものとまったく同じ内容をゲートウェイがその URL へ送ります。署名付きで、届かなかった場合は自動で再試行します。コンソールの「設定 → Webhook」で、アカウント全体の送信先を設定することもできます。 [Webhook のドキュメント →](https://docs.kovapi.com/ja/webhooks)

```
curl https://kovapi.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedance-2.5-30s", "prompt": "秋の谷あいの町を旅人が夜明けから夕暮れまで歩いていく、カメラがずっと後を追う", "duration": 25, "resolution": "720P", "size": "16:9", "callback_url": "https://your-domain.com/webhook"}'
```