--- title: "Create a reference video task" description: "Generates a video guided by reference images, and depending on the model, reference videos and audio." canonical: "https://platform.pixai.art/en/docs/api-v2/video/createReferenceVideo" last-updated: "2026-11-02" --- # Create a reference video task Generates a video guided by reference images, and depending on the model, reference videos and audio. Each model accepts different references: * `tbkv1.0.1`, `tbkv1.0` (Tsubaki): 1–6 images, no videos, up to 3 audio clips, `duration` 5–15. * `v4.0`, `v4.0.1` (Seedance 2, Seedance 2 Fast): up to 9 images, up to 3 videos, up to 3 audio clips, `duration` 4–15. * `v4.0.3` (Seedance 2.5): up to 30 images, up to 10 videos, up to 10 audio clips, `duration` 4–30. * `v3.3` (Vidu): 1–7 images, no videos or audio, `duration` 3–16. Every model needs at least one image or video, except `v4.0.3`, which also accepts audio alone. Reference files must meet these limits: * Video: MP4 or MOV, H.264 or HEVC, 24–60 fps, 2–15 s per clip and 15 s in total (30 s on `v4.0.3`), up to 50 MB (200 MB on `v4.0.3`). * Audio: WAV or MP3, 2–15 s per clip and 15 s in total (30 s on `v4.0.3`), under 15 MiB. Check a file with `GET /v2/media/{mediaId}/info` before sending it. On `v4.0` and `v4.0.1`, counts and clip lengths are checked after the task is charged: a task that breaks them fails instead of being refused. Credits are charged when the task is created. Poll `GET /v2/task/{id}` for the result; a finished task's video is `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.yaml ### Request body (`application/json`) - `model` (string, required) The video model. See the table above for what each accepts. An unknown value answers `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) What should happen in the video. Describe how to use the references. Default: `null`. - `referenceImageMediaIds` (string[], optional) Image media IDs. Default: `[]`. - `referenceVideoMediaIds` (string[], optional) Video media IDs. Not accepted by Tsubaki or Vidu. Default: `[]`. - `referenceAudioMediaIds` (string[], optional) Audio media IDs, uploaded with `POST /v2/media/audio/upload-url`. Not accepted by Vidu. Default: `[]`. - `duration` (integer, optional) Length in whole seconds. The allowed range depends on `model`. Default: `5`. - `ratio` (string, optional) Output aspect ratio. Omitted or `adaptive` follows the references. Seedance models do not take `2:3` or `3:2`, and Vidu ignores this field. Allowed values: `adaptive`, `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9`, `21:9`. - `mode` (string, optional) `professional` adds an upscale (1080p on `v4.0`, 720p on `v4.0.1`) and costs more. Not accepted by `v4.0.3`. Allowed values: `basic`, `professional`. Default: `"basic"`. - `generateAudio` (boolean, optional) Whether to generate a soundtrack. Default: `true`. - `audioLanguage` (string | null, optional) Language of speech in the soundtrack. `none` for no speech. 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` The task was created. Poll `GET /v2/task/{id}` with its `id`. Body fields: - `id` (string, required) The unique identifier for the task. - `status` (string, required) The current status of the task. Allowed values: `waiting`, `running`, `completed`, `cancelled`, `failed`. - `createdAt` (string, required) The time the task was created. - `updatedAt` (string, required) The time the task was last updated. - `startedAt` (string, optional) The time the task started running. - `endAt` (string, optional) The time the task finished. - `taskKind` (string, optional) What the task makes: `t2i` or `i2i` for images, `inpaint` for `POST /v2/gen-task/inpaint`, `i2v-inhouse` for `POST /v2/frame-video/create`, `reference-video` for `POST /v2/reference-video/create`. - `paidQuota` (integer, optional) Credits charged for the task. - `taskStatusMsgI18n` (object, optional) Why a `failed` task failed. - `taskStatusMsgI18n.key` (string, optional) A stable message key. - `taskStatusMsgI18n.defaultMessage` (string, optional) The message in English. - `outputs` (object, optional) The outputs produced by the task. - `outputs.videoMediaId` (string, optional) For video tasks, the media ID of the video. Resolve it with `GET /v2/media/batch?ids=` and download `fileUrl`. `mediaIds` then holds only the poster image. - `outputs.seed` (string, optional) The seed used, as a decimal string. - `outputs.mediaIds` (string[], optional) Media IDs of the generated images. Use these IDs to fetch detailed information about each generated image. Generated images are not permanently retained — retrieve them as soon as possible. - `outputs.mediaUrls` ((string | null)[], optional) Public URLs of the generated images. Generated images are not permanently retained — retrieve them as soon as possible. If an image is unavailable, its entry may be `null`. - `400` - `BAD_REQUEST` with `data.issues`: the body failed validation, e.g. too many references for `v4.0.3`. - `VALIDATION_ERROR`: the combination is not valid for this model, e.g. `mode: professional` on `v4.0.3`, or a video or audio reference for Vidu. `message` says which. - `401` `UNAUTHORIZED`: no API key was sent. An invalid, revoked or expired key answers `{"message": "invalid token", "code": 40100001}` instead, with a numeric `code`. - `403` The account cannot run this task right now. `code` says why: - `INSUFFICIENT_BALANCE`: not enough credits for the task. - `WAITING_NUM_EXCEEDED`: too many of your tasks are still `waiting` (`data.currentWaitingTasks`). Wait for some to start before submitting more. - `REQUIRE_MEMBERSHIP`: the feature needs a PixAI membership (image-to-video). - `NSFW_PROMPTS_DETECTED`: the prompt was refused because the account is in safe mode. - `422` `INVALID_INPUT`: a reference file was refused before the task was charged. `message` reads `Invalid reference media: `, sometimes followed by the media ID in parentheses. Reasons include `too_many_reference_images`, `reference_video_not_supported` and `unsupported_reference_video_format`. - `500` `CREATION_FAILED`: the task could not be created. Retry with exponential backoff.