> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pixverse v6 비디오 생성

>  - Pixverse v6 통합 비디오 생성 모델
- 텍스트→비디오, 이미지→비디오, 시작/종료 프레임 전환, 다중 참조 이미지 융합, 비디오 연장 지원
- 360p/540p/720p/1080p 해상도, 1-15초 비디오 길이 지원
- 비동기 작업 API. 제출 후 작업 ID로 결과를 조회합니다. 

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.apimart.ai/v1/videos/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "pixverse-v6",
      "prompt": "A cinematic shot of a corgi running through a sunflower field at golden hour",
      "size": "16:9",
      "resolution": "540p",
      "duration": 5
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.apimart.ai/v1/videos/generations"

  payload = {
      "model": "pixverse-v6",
      "prompt": "A cinematic shot of a corgi running through a sunflower field at golden hour",
      "size": "16:9",
      "resolution": "540p",
      "duration": 5
  }

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://api.apimart.ai/v1/videos/generations";

  const payload = {
    model: "pixverse-v6",
    prompt: "A cinematic shot of a corgi running through a sunflower field at golden hour",
    size: "16:9",
    resolution: "540p",
    duration: 5
  };

  const headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  };

  fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload)
  })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error("Error:", error));
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01JWXXXXXXXXXXXX"
      }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "type": "invalid_request_error",
      "message": "invalid duration 20, allowed range: 1-15 seconds"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": 401,
      "message": "인증에 실패했습니다. API 키를 확인하세요",
      "type": "authentication_error"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": 403,
      "message": "insufficient quota: balance=0, required=0.25",
      "type": "quota_not_enough"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": 429,
      "message": "요청이 너무 많습니다. 잠시 후 다시 시도하세요",
      "type": "rate_limit_error"
    }
  }
  ```
</ResponseExample>

## 인증

<ParamField header="Authorization" type="string" required>
  모든 엔드포인트는 Bearer Token 인증이 필요합니다.

  API Key 발급:

  [API Key 관리 페이지](https://apimart.ai/keys)에 접속하여 API Key를 발급받으세요.

  요청 헤더에 다음을 추가합니다:

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## 요청 파라미터

<ParamField body="model" type="string" required>
  비디오 생성 모델명. `pixverse-v6`로 고정됩니다.
</ParamField>

<ParamField body="prompt" type="string" required>
  비디오 콘텐츠 설명. 최대 5000자. 모든 모드에서 필수입니다.
</ParamField>

<ParamField body="resolution" type="string" default="540p">
  비디오 해상도. 과금에 직접 영향을 줍니다.

  * `360p`: SD
  * `540p`: 표준 (기본값)
  * `720p`: HD
  * `1080p`: Full HD

  <Warning>
    지정되지 않은 해상도는 파라미터 오류를 반환합니다.
  </Warning>
</ParamField>

<ParamField body="duration" type="integer" default="5">
  비디오 길이(초). 범위는 `1-15`.

  <Warning>
    시작/종료 프레임 전환 모드는 `5` 또는 `8`초만 지원합니다.
  </Warning>
</ParamField>

<ParamField body="size" type="string" default="16:9">
  비디오 화면 비율. 텍스트→비디오와 다중 참조 이미지 융합 모드에서만 적용됩니다.

  * `16:9`: 가로 와이드 (기본값)
  * `4:3`: 가로 4:3
  * `1:1`: 정사각형
  * `3:4`: 세로 3:4
  * `9:16`: 세로 (모바일)
  * `2:3`: 세로 2:3
  * `3:2`: 가로 3:2
  * `21:9`: 시네마 와이드
</ParamField>

<ParamField body="seed" type="integer" default="0">
  랜덤 시드. 범위는 `0-2147483647`. 동일한 prompt와 seed로 유사한 결과를 재현할 수 있습니다.
</ParamField>

<ParamField body="negative_prompt" type="string">
  네거티브 프롬프트. 원치 않는 콘텐츠를 제외하는 데 사용. 최대 2048자.
</ParamField>

<ParamField body="audio" type="boolean" default="false">
  오디오 트랙 생성 여부.

  * `true`: 오디오 생성 (과금 단가가 상승)
  * `false`: 오디오 미생성 (기본값)
</ParamField>

<ParamField body="watermark" type="boolean" default="false">
  비디오 우측 하단에 워터마크 추가 여부.

  * `true`: 워터마크 추가
  * `false`: 워터마크 미추가 (기본값)
</ParamField>

<ParamField body="motion_mode" type="string">
  모션 모드.

  * `normal`: 표준 모드 (`pixverse-v6`은 이 값만 지원)

  <Warning>
    `fast`는 구버전 모델 전용입니다. `pixverse-v6`에 사용하면 업스트림에서 거부됩니다.
  </Warning>
</ParamField>

<ParamField body="generate_multi_clip_switch" type="boolean" default="false">
  다중 클립 연속 비디오 생성 여부. 텍스트→비디오 및 이미지→비디오 모드에서만 지원합니다.

  * `true`: 다중 클립 연속 비디오 생성
  * `false`: 단일 클립 (기본값)
</ParamField>

<ParamField body="image_urls" type="array<url>">
  이미지→비디오의 입력 이미지 URL 배열. 첫 번째 이미지만 사용됩니다.

  이미지는 공개적으로 접근 가능한 HTTP/HTTPS URL이어야 합니다.
</ParamField>

<ParamField body="first_frame_image" type="url">
  시작/종료 프레임 전환 모드의 시작 프레임 이미지 URL. `last_frame_image`와 반드시 함께 전달해야 합니다.
</ParamField>

<ParamField body="last_frame_image" type="url">
  시작/종료 프레임 전환 모드의 종료 프레임 이미지 URL. `first_frame_image`와 반드시 함께 전달해야 합니다.
</ParamField>

<ParamField body="img_references" type="array<url>">
  다중 참조 이미지 융합 모드의 참조 이미지 URL 배열. 1-7장 지원.

  이 필드를 전달하면 다중 참조 이미지 융합 모드가 활성화됩니다.
</ParamField>

<ParamField body="extend_from_task_id" type="string">
  비디오 연장 소스 작업 ID. 이 필드를 전달하면 비디오 연장 모드가 활성화됩니다.

  소스 작업은 현재 사용자의 것이어야 하며, 모델은 `pixverse-v6`, 상태는 `completed`여야 합니다.
</ParamField>

## 생성 모드

어댑터는 요청 필드에 따라 자동으로 해당 생성 모드로 분배합니다. 우선순위 순서로 매칭하며, 가장 먼저 조건을 만족하는 모드가 선택됩니다.

| 모드           | 트리거 조건                                        | 설명                        |
| ------------ | --------------------------------------------- | ------------------------- |
| 텍스트→비디오      | 이미지/연장 필드 미전달                                 | `prompt`로 비디오 생성          |
| 이미지→비디오      | `image_urls`에 이미지 1장 전달                       | 첫 번째 이미지를 입력으로 사용         |
| 시작/종료 프레임 전환 | `first_frame_image`와 `last_frame_image` 동시 전달 | 두 프레임 사이의 부드러운 전환 생성      |
| 다중 참조 이미지 융합 | `img_references` 배열 전달                        | 1-7장의 참조 이미지를 융합하여 비디오 생성 |
| 비디오 연장       | `extend_from_task_id` 전달                      | 완료된 Pixverse 작업에서 이어서 생성  |

<Warning>
  모든 이미지 입력은 공개적으로 접근 가능한 HTTP/HTTPS URL만 지원합니다. base64 또는 Data URI는 지원하지 않습니다. 로컬 이미지만 있는 경우, 먼저 오브젝트 스토리지에 업로드한 후 URL을 전달하세요.
</Warning>

## 파라미터 규칙

| 제한           | 설명                                                                  |
| ------------ | ------------------------------------------------------------------- |
| 비디오 길이       | `1 ≤ duration ≤ 15`초. 전환 모드는 `5` 또는 `8`초만                           |
| 해상도          | `360p`, `540p`, `720p`, `1080p`만 지원                                 |
| 화면 비율        | `size`는 텍스트→비디오 및 다중 참조 이미지 융합 모드에서만 적용                             |
| 프롬프트 길이      | `prompt` 최대 5000자, `negative_prompt` 최대 2048자                       |
| 이미지→비디오      | `image_urls`는 첫 번째 이미지만 사용                                          |
| 시작/종료 프레임 전환 | `first_frame_image`와 `last_frame_image`를 쌍으로 전달                     |
| 모션 모드        | `pixverse-v6`은 `normal`만 지원                                         |
| 다중 참조 이미지 융합 | `img_references`는 1-7장 지원                                           |
| 비디오 연장       | `extend_from_task_id`는 현재 사용자의 `completed` 상태 `pixverse-v6` 작업이어야 함 |

## 응답

<ResponseField name="code" type="integer">
  응답 상태 코드. 성공 시 `200`.
</ResponseField>

<ResponseField name="data" type="array">
  반환되는 작업 배열.

  <Expandable title="배열 요소">
    <ResponseField name="status" type="string">
      작업의 초기 상태. 제출 성공 시 `submitted`.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      작업의 고유 식별자. 작업 상태 및 결과 조회에 사용됩니다.
    </ResponseField>
  </Expandable>
</ResponseField>

## 작업 결과 조회

비디오 생성은 비동기 작업입니다. 제출 후 `task_id`가 반환되며, [작업 상태 가져오기](/ko/api-reference/tasks/status) 엔드포인트로 진행 상황과 결과를 조회하세요.

```bash cURL theme={null}
curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01JWXXXXXXXXXXXX \
  --header 'Authorization: Bearer <token>'
```

상태가 `completed` 또는 `failed`로 변경될 때까지 5초 간격으로 폴링하는 것을 권장합니다.

### 성공 결과 예시

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KSPX48B8V1M6C2ZN0D0T4BKB",
    "status": "completed",
    "progress": 100,
    "cost": 0.2,
    "credits_cost": 2,
    "created": 1779958948,
    "completed": 1779958999,
    "estimated_time": 100,
    "actual_time": 51,
    "result": {
      "videos": [
        {
          "url": ["https://upload.apimart.ai/f/video/xxxx.mp4"],
          "expires_at": 1780045399
        }
      ]
    }
  }
}
```

비디오 URL 경로는 `data.result.videos[0].url[0]`입니다. `url` 필드 자체도 배열입니다. 비디오 링크는 일반적으로 24시간 후 만료되므로 즉시 다운로드하거나 전송하세요.

### 실패 결과 예시

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KSPX48B8V1M6C2ZN0D0T4BKB",
    "status": "failed",
    "progress": 100,
    "cost": 0,
    "credits_cost": 0,
    "created": 1779958948,
    "completed": 1779958960,
    "error": {
      "code": "task_failed",
      "message": "pixverse error 400063: moderation failed",
      "type": "task_failed"
    }
  }
}
```

실패 시 `cost`는 일반적으로 `0`이며, 오류 원인은 `data.error.message`에서 확인하세요.

## 사용 시나리오

### 시나리오 1: 텍스트→비디오

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "A neon-lit alley in Tokyo at night, light rain, anamorphic lens flare",
  "size": "21:9",
  "resolution": "720p",
  "duration": 8,
  "seed": 42,
  "audio": true
}
```

### 시나리오 2: 이미지→비디오

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "Camera slowly zooms in, gentle wind moves the leaves",
  "image_urls": ["https://example.com/first-frame.jpg"],
  "resolution": "540p",
  "duration": 5
}
```

### 시나리오 3: 시작/종료 프레임 전환

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "transform smoothly from a puppy to a cat",
  "first_frame_image": "https://example.com/puppy.jpg",
  "last_frame_image": "https://example.com/cat.jpg",
  "resolution": "540p",
  "duration": 5,
  "motion_mode": "normal"
}
```

### 시나리오 4: 다중 참조 이미지 융합

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "A girl wearing the outfit from image 2, holding the cat from image 3",
  "img_references": [
    "https://example.com/character.jpg",
    "https://example.com/outfit.jpg",
    "https://example.com/cat.jpg"
  ],
  "size": "9:16",
  "resolution": "720p",
  "duration": 5
}
```

### 시나리오 5: 비디오 연장

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "the character now walks into a forest",
  "extend_from_task_id": "task_01JWXXXXXXXXXXXX",
  "resolution": "540p",
  "duration": 5
}
```