---
title: "이미지 기반 동영상 생성 작업 생성"
description: "PixAI의 Tsubaki 동영상 모델로 이미지를 동영상으로 만듭니다. 동영상은 firstFrameMediaId에서 시작하며, lastFrameMediaId를 보내면 그 프레임에서 끝납니다. 출력은 첫 프레임의 종횡비를 유지합니다."
canonical: "https://platform.pixai.art/ko/docs/api-v2/video/createFrameVideo"
last-updated: "2026-11-02"
---

# 이미지 기반 동영상 생성 작업 생성

PixAI의 Tsubaki 동영상 모델로 이미지를 동영상으로 만듭니다. 동영상은 `firstFrameMediaId`에서 시작하며, `lastFrameMediaId`를 보내면 그 프레임에서 끝납니다. 출력은 첫 프레임의 종횡비를 유지합니다.



프레임은 이미지 미디어 ID입니다. `POST /v2/media/image/upload-url`로 직접 업로드하거나 생성한 이미지를 재사용하세요. 다른 사용자가 소유한 미디어는 거부됩니다.

이미지 기반 동영상 생성에는 PixAI 멤버십이 필요합니다. 크레딧은 작업 생성 시 차감됩니다. 결과는 `GET /v2/task/{id}`를 폴링하여 확인하며, 완료된 작업의 동영상은 `outputs.videoMediaId`입니다.

## POST https://api.pixai.art/v2/frame-video/create

Authentication: send your API key as `Authorization: Bearer <API key>`.

Machine-readable OpenAPI spec: https://platform.pixai.art/openapi-spec.v2.ko.yaml

### Request body (`application/json`)

- `model` (string, required)
  동영상 모델입니다. `tbkv1.0.1`이 최신 Tsubaki 동영상 모델입니다.
  Allowed values: `tbkv1.0.1`, `tbkv1.0`.
- `firstFrameMediaId` (string, required)
  첫 프레임의 이미지 미디어 ID입니다.
- `lastFrameMediaId` (string, optional)
  마지막 프레임의 이미지 미디어 ID입니다. 루프 영상을 만들려면 첫 프레임을 다시 보내세요.
- `prompt` (string | null, optional)
  동영상에서 일어날 내용입니다.
  Default: `null`.
- `duration` (integer, optional)
  길이(정수 초)입니다.
  Default: `5`.
  Range: 5 to 15.
- `mode` (string, optional)
  `professional`은 `tbkv1.0.1`에서 1080p 업스케일을 추가하며 비용이 더 듭니다. `tbkv1.0`에서는 효과가 없습니다.
  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",
  "firstFrameMediaId": "1943547603237249965",
  "prompt": "she turns around and smiles, hair blowing in the wind",
  "duration": 5
}
```

### Example (cURL)

```bash
curl -X POST https://api.pixai.art/v2/frame-video/create \
  -H "Authorization: Bearer $PIXAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tbkv1.0.1",
    "firstFrameMediaId": "1943547603237249965",
    "prompt": "she turns around and smiles, hair blowing in the wind",
    "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=<videoMediaId>`로 조회한 뒤 `fileUrl`을 다운로드하세요. 이때 `mediaIds`에는 포스터 이미지만 들어 있습니다.
  - `outputs.seed` (string, optional)
    사용된 시드 값(10진수 문자열).
  - `outputs.mediaIds` (string[], optional)
    생성된 이미지의 미디어 ID입니다. 이 ID를 사용하여 각 생성 이미지의 상세 정보를 조회할 수 있습니다.

    생성된 이미지는 일반적으로 영구 보관되지 않으므로 가능한 한 빨리 다운로드해 주세요.
  - `outputs.mediaUrls` ((string | null)[], optional)
    생성된 이미지의 공개 URL입니다.

    생성된 이미지는 일반적으로 영구 보관되지 않으므로 가능한 한 빨리 다운로드해 주세요. 이미지가 사용 불가능한 경우 해당 항목이 `null`로 표시될 수 있습니다.
- `400`
  - `INVALID_REFERENCE_MEDIA`: 프레임이 없거나, 이미지가 아니거나, 다른 사용자의 것입니다. `data.code`는 `invalid_input` 또는 `media_not_owned`이며, `data.mediaId`가 해당 프레임을 나타냅니다.
  - `BAD_REQUEST`(`data.issues` 포함): 본문 검증에 실패했습니다.
- `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`: 계정이 세이프 모드여서 프롬프트가 거부되었습니다.
- `500`
  `CREATION_FAILED`: 작업을 생성하지 못했습니다. 지수 백오프로 재시도하세요.