--- title: "参照動画生成タスクの作成" description: "参照画像に基づいて動画を生成します。モデルによっては参照動画と参照音声も使用できます。" canonical: "https://platform.pixai.art/ja/docs/api-v2/video/createReferenceVideo" last-updated: "2026-11-02" --- # 参照動画生成タスクの作成 参照画像に基づいて動画を生成します。モデルによっては参照動画と参照音声も使用できます。 受け付ける参照はモデルごとに異なります: * `tbkv1.0.1`、`tbkv1.0`（Tsubaki）: 画像 1〜6、動画不可、音声クリップ最大 3、`duration` 5〜15。 * `v4.0`、`v4.0.1`（Seedance 2、Seedance 2 Fast）: 画像最大 9、動画最大 3、音声クリップ最大 3、`duration` 4〜15。 * `v4.0.3`（Seedance 2.5）: 画像最大 30、動画最大 10、音声クリップ最大 10、`duration` 4〜30。 * `v3.3`（Vidu）: 画像 1〜7、動画・音声不可、`duration` 3〜16。 どのモデルでも画像または動画が 1 つ以上必要です。ただし `v4.0.3` は音声のみでも受け付けます。 参照ファイルは次の制限を満たす必要があります: * 動画: MP4 または MOV、H.264 または HEVC、24〜60 fps、1 クリップ 2〜15 秒・合計 15 秒（`v4.0.3` では 30 秒）、最大 50 MB（`v4.0.3` では 200 MB）。 * 音声: WAV または MP3、1 クリップ 2〜15 秒・合計 15 秒（`v4.0.3` では 30 秒）、15 MiB 未満。 送信前に `GET /v2/media/{mediaId}/info` でファイルを確認してください。`v4.0` と `v4.0.1` では、数やクリップの長さはタスクの課金後にチェックされます。制限に違反したタスクは拒否されずに失敗します。 クレジットはタスク作成時に消費されます。結果は `GET /v2/task/{id}` をポーリングして取得します。完了したタスクの動画は `outputs.videoMediaId` です。 ## POST https://api.pixai.art/v2/reference-video/create Authentication: send your API key as `Authorization: Bearer `. Machine-readable OpenAPI spec: https://platform.pixai.art/openapi-spec.v2.ja.yaml ### Request body (`application/json`) - `model` (string, required) 動画モデルです。各モデルが受け付ける参照は上の表を参照してください。不明な値には `403 MODEL_VERSION_NOT_EXISTS` が返ります。 Allowed values: `tbkv1.0.1`, `tbkv1.0`, `v4.0`, `v4.0.1`, `v4.0.3`, `v3.3`. - `prompt` (string | null, optional) 動画の中で起こる内容です。参照の使い方を記述してください。 Default: `null`. - `referenceImageMediaIds` (string[], optional) 画像のメディア ID です。 Default: `[]`. - `referenceVideoMediaIds` (string[], optional) 動画のメディア ID です。Tsubaki と Vidu では使えません。 Default: `[]`. - `referenceAudioMediaIds` (string[], optional) `POST /v2/media/audio/upload-url` でアップロードした音声のメディア ID です。Vidu では使えません。 Default: `[]`. - `duration` (integer, optional) 長さ（秒、整数）です。指定できる範囲は `model` によって異なります。 Default: `5`. - `ratio` (string, optional) 出力のアスペクト比です。省略するか `adaptive` を指定すると参照に合わせます。Seedance モデルは `2:3` と `3:2` に対応しておらず、Vidu はこのフィールドを無視します。 Allowed values: `adaptive`, `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9`, `21:9`. - `mode` (string, optional) `professional` はアップスケール（`v4.0` で 1080p、`v4.0.1` で 720p）を追加し、料金が高くなります。`v4.0.3` では使えません。 Allowed values: `basic`, `professional`. Default: `"basic"`. - `generateAudio` (boolean, optional) サウンドトラックを生成するかどうか。 Default: `true`. - `audioLanguage` (string | null, optional) サウンドトラック内の音声の言語です。音声なしは `none` です。 Allowed values: `none`, `chinese`, `english`, `japanese`, `korean`, `null`. Default: `null`. Example: ```json { "model": "tbkv1.0.1", "prompt": "the girl walks through the city at night", "referenceImageMediaIds": [ "1943547603237249965" ], "ratio": "9:16", "duration": 5 } ``` ### Example (cURL) ```bash curl -X POST https://api.pixai.art/v2/reference-video/create \ -H "Authorization: Bearer $PIXAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "tbkv1.0.1", "prompt": "the girl walks through the city at night", "referenceImageMediaIds": ["1943547603237249965"], "ratio": "9:16", "duration": 5 }' ``` ### Responses - `201` タスクを作成しました。その `id` で `GET /v2/task/{id}` をポーリングしてください。 Body fields: - `id` (string, required) タスクの一意の識別子。 - `status` (string, required) タスクの現在のステータス。 Allowed values: `waiting`, `running`, `completed`, `cancelled`, `failed`. - `createdAt` (string, required) タスクの作成時刻。 - `updatedAt` (string, required) タスクの最終更新時刻。 - `startedAt` (string, optional) タスクの開始時刻。 - `endAt` (string, optional) タスクの終了時刻。 - `taskKind` (string, optional) タスクが生成するもの。画像は `t2i` または `i2i`、`POST /v2/gen-task/inpaint` は `inpaint`、`POST /v2/frame-video/create` は `i2v-inhouse`、`POST /v2/reference-video/create` は `reference-video` です。 - `paidQuota` (integer, optional) タスクに課金されたクレジット。 - `taskStatusMsgI18n` (object, optional) `failed` になったタスクの失敗理由。 - `taskStatusMsgI18n.key` (string, optional) 変わらないメッセージキー。 - `taskStatusMsgI18n.defaultMessage` (string, optional) 英語のメッセージ。 - `outputs` (object, optional) タスクで生成された出力。 - `outputs.videoMediaId` (string, optional) 動画タスクの場合、動画のメディア ID です。`GET /v2/media/batch?ids=` で解決し、`fileUrl` をダウンロードしてください。このとき `mediaIds` にはポスター画像だけが入ります。 - `outputs.seed` (string, optional) 使われたシード値（10 進数の文字列）。 - `outputs.mediaIds` (string[], optional) 生成された画像のメディア ID です。これらの ID を使用して各生成画像の詳細情報を取得できます。 生成された画像は通常、恒久的には保持されません。できるだけ早く取得してください。 - `outputs.mediaUrls` ((string | null)[], optional) 生成された画像の公開 URL です。 生成された画像は通常、恒久的には保持されません。できるだけ早く取得してください。画像が利用できない場合、その項目は `null` になることがあります。 - `400` - `BAD_REQUEST`（`data.issues` あり）: ボディの検証に失敗しました（`v4.0.3` で参照が多すぎる場合など）。 - `VALIDATION_ERROR`: このモデルでは無効な組み合わせです（`v4.0.3` での `mode: professional`、Vidu への動画や音声の参照など）。`message` に詳細が示されます。 - `401` `UNAUTHORIZED`: API キーが送られていません。無効、失効済み、期限切れのキーの場合は、数値の `code` を持つ `{"message": "invalid token", "code": 40100001}` が返ります。 - `403` 現在このアカウントではこのタスクを実行できません。理由は `code` で示されます: - `INSUFFICIENT_BALANCE`: タスクに必要なクレジットが不足しています。 - `WAITING_NUM_EXCEEDED`: `waiting` 状態のタスクが多すぎます（`data.currentWaitingTasks`）。いくつか実行が始まるまで待ってから送信してください。 - `REQUIRE_MEMBERSHIP`: この機能には PixAI メンバーシップが必要です（画像から動画への生成）。 - `NSFW_PROMPTS_DETECTED`: アカウントがセーフモードのため、プロンプトが拒否されました。 - `422` `INVALID_INPUT`: タスクの課金前に参照ファイルが拒否されました。`message` は `Invalid reference media: ` の形式で、メディア ID が括弧付きで続くことがあります。理由は `too_many_reference_images`、`reference_video_not_supported`、`unsupported_reference_video_format` などです。 - `500` `CREATION_FAILED`: タスクを作成できませんでした。指数バックオフで再試行してください。