--- title: "참조 동영상 생성 작업 생성" description: "참조 이미지와, 모델에 따라 참조 동영상 및 오디오를 바탕으로 동영상을 생성합니다." canonical: "https://platform.pixai.art/ko/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. 모든 모델에는 이미지나 동영상이 하나 이상 필요합니다. 단, `v4.0.3`은 오디오만으로도 생성할 수 있습니다. 참조 파일은 다음 제한을 충족해야 합니다: * 동영상: MP4 또는 MOV, H.264 또는 HEVC, 24–60 fps, 클립당 2–15초, 합계 15초(`v4.0.3`은 30초), 최대 50 MB(`v4.0.3`은 200 MB). * 오디오: WAV 또는 MP3, 클립당 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.ko.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`: 작업을 생성하지 못했습니다. 지수 백오프로 재시도하세요.