> ## 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.

# apimart-zoe 동영상 생성

> 텍스트, 프레임, 이미지·동영상·오디오 참조로 동영상을 생성하고 편집합니다. 480p–4k, 마지막 프레임 이미지, MOV 및 초안에서 최종 영상 생성을 지원합니다.

> [!NOTE]
>
> 비동기 API입니다. 제출 후 `data[0].task_id`를 읽고 [작업 상태 조회](https://docs.apimart.ai/ko/api-reference/tasks/status.md)로 결과를 확인하세요. 보통 1–3분이 걸리며 5–10초 간격으로 조회하는 것이 좋습니다. 실제 소요 시간은 작업에 따라 달라집니다.

```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": "apimart-zoe",
    "prompt": "창가의 주황색 아기 고양이가 카메라를 바라보고 옆에서 햇빛이 들어오며 카메라가 천천히 다가간다",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 8,
    "audio": true,
    "nsfw_check": true,
    "return_last_frame": true
  }'
```

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

response = requests.post(
    "https://api.apimart.ai/v1/videos/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "apimart-zoe",
        "prompt": "창가의 주황색 아기 고양이가 카메라를 바라보고 옆에서 햇빛이 들어오며 카메라가 천천히 다가간다",
        "resolution": "1080p",
        "aspect_ratio": "16:9",
        "duration": 8,
        "audio": True,
        "nsfw_check": True,
        "return_last_frame": True
    }
)
response.raise_for_status()
print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.apimart.ai/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "model": "apimart-zoe",
    "prompt": "창가의 주황색 아기 고양이가 카메라를 바라보고 옆에서 햇빛이 들어오며 카메라가 천천히 다가간다",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 8,
    "audio": true,
    "nsfw_check": true,
    "return_last_frame": true
  })
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KZOEEXAMPLE"
    }
  ]
}
```

## 모드 선택

| 모드 | 설정 방법 |
| - | - |
| 텍스트 → 동영상 | 미디어 없이 `prompt`를 전달합니다. |
| 첫·마지막 프레임 → 동영상 | `image_with_roles`의 `first_frame`과 선택적 `last_frame` 역할, 또는 `first_frame_image` / `last_frame_image`를 전달합니다. |
| 참조 → 동영상 | 참조 이미지 또는 동영상을 사용하고 참조 오디오를 추가할 수 있습니다. 오디오만 사용할 수 없습니다. |
| 초안 | `draft: true`로 `480p` 영상을 생성합니다. |
| 최종 영상 | 성공한 초안의 `draft_task_id`로 `1080p` 영상을 생성합니다. |
| 동영상 편집 | `omni_reference_task_type: "edit"`와 원본 동영상 1개 이상을 전달합니다. 출력 길이와 화면비는 원본을 따릅니다. |

## 요청 헤더

**Authorization** `string` *required*

`Bearer <token>` 형식의 Bearer 인증을 사용합니다. `<token>`은 APIMart API 키입니다. 본문은 `Content-Type: application/json`으로 전송합니다.

## 요청 매개변수

**model** `string` *required*

`apimart-zoe`로 고정합니다.

**prompt** `string`

최대 204,800자. 텍스트 기반 생성에는 필수이며 미디어만 전달할 때는 생략할 수 있습니다. `draft_task_id`로 최종 영상을 생성할 때는 전달할 수 없고 초안의 프롬프트를 그대로 사용합니다.

**resolution** `string`

`480p`, `720p`, `1080p`, `2k`, `4k`를 지원하며 대소문자를 구분하지 않습니다. 일반 생성의 기본값은 `720p`입니다. `draft: true`는 `480p`만 지원하며 생략해도 `480p`입니다. `draft_task_id`는 `1080p`만 지원하며 생략해도 `1080p`입니다.

**aspect\_ratio** `string`

`21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `adaptive`를 지원합니다. 기본값은 모델 또는 미디어가 결정하는 `adaptive`입니다. 최종 영상에서는 생략하며 초안의 화면비를 따릅니다.

동영상 편집(`edit`)에서는 생략하거나 `adaptive`만 전달하며 원본 화면비를 따릅니다.

**size** `string`

`aspect_ratio`의 다른 이름이며 같은 값을 지원합니다. 둘 중 하나만 보내는 것을 권장합니다. 최종 영상 생성 시 생략하세요.

**duration** `integer`

일반 생성: `4`–`30` 정수 초, 기본값 `5`. 지정값 또는 기본값으로 과금하며 완성된 영상 길이로 조정하지 않습니다. `-1`이면 모델이 결정합니다. 제출 시 30초분을 선차감하고 완료 후 실제 길이를 정수 초로 반올림해 정산합니다. 최종 영상에서는 생략하며 초안 길이를 따릅니다.

동영상 편집(`edit`)에서는 생략하거나 `-1`만 전달하세요. 생략 시에도 `-1`로 처리하며 출력 길이는 원본을 따릅니다.

**seconds** `integer`

`duration`의 별칭으로 동일한 규칙이 적용됩니다. 둘 중 하나만 사용하세요. 최종 영상 생성 시 생략합니다.

**audio** `boolean`

동영상과 함께 오디오를 생성할지 정하는 불리언 값입니다. 별칭은 `generate_audio`이며 생략하면 모델이 결정합니다. 최종 영상 생성 시 전달할 수 없습니다. 입력 참조인 `audio_urls`와 달리 출력 오디오를 제어합니다.

`audio`와 `generate_audio`를 모두 전달하면 값이 같아야 하며 다르면 HTTP 400입니다. 생략하면 모델이 결정하며 보통 소리를 포함합니다.

**generate\_audio** `boolean`

`audio`의 별칭으로 같은 규칙을 적용합니다. 둘 중 하나만 사용하고 최종 영상에서는 생략하세요.

`audio`와 `generate_audio`를 모두 전달하면 값이 같아야 하며 다르면 HTTP 400입니다. 생략하면 모델이 결정하며 보통 소리를 포함합니다.

**seed** `integer`

정수형 랜덤 시드입니다. 최종 영상 생성 시 전달할 수 없습니다.

**nsfw\_check** `boolean`

기본적으로 심사하지 않습니다. `true`로 활성화합니다.

선택적 불리언 값입니다. `true`이면 `prompt`, `image_urls`, `image_with_roles`, 첫·마지막 프레임 이미지, `asset://` 이미지 미디어를 심사합니다. 참조 동영상과 오디오는 심사하지 않습니다.

최종 영상 요청에는 프롬프트와 미디어가 없으므로 초안 → 최종 영상 흐름에서는 초안 생성 시 심사합니다.

감지 시 HTTP 400(`nsfw_content_detected`)을 반환하고 `error.message`에 감지 범주를 포함합니다. 일반 매개변수 오류가 아니라 심사 거부로 표시하세요. 심사 서비스 오류나 호출 실패 시 생성 요청을 계속 제출하므로 이 설정이 모든 요청의 심사 완료를 보장하지는 않습니다.

**omni\_reference\_task\_type** `string`

`auto`(기본값, 생략과 같으며 모델이 판단), `reference`, `edit`를 지원합니다. `reference` / `edit`는 참조 미디어가 있어야 하며 텍스트 전용 또는 첫·마지막 프레임 요청에서는 HTTP 400입니다. `edit`는 `video_urls`에 최소 1개가 필요하고 `draft: true`와 함께 사용할 수 없습니다. `extend`는 미지원이며 HTTP 400을 반환합니다. 최종 영상 생성에는 전달하지 마세요.

**return\_last\_frame** `boolean`

`true`로 설정하면 마지막 프레임의 PNG 이미지를 `data.result.last_frame_url`로 추가 반환합니다. 기본적으로 반환하지 않습니다. 최종 영상 생성에는 전달하지 마세요.

**output\_format** `string`

`mp4`(기본값) 또는 `mov`(QuickTime 컨테이너)를 지원하며 다른 값은 HTTP 400입니다. 별칭은 `response_format`이며 둘 다 전달하면 `output_format`이 우선합니다. 최종 영상 생성에는 전달하지 마세요.

**response\_format** `string`

`output_format`의 별칭으로 `mp4` / `mov`를 지원합니다. 둘 다 전달하면 `output_format`이 우선합니다. 최종 영상 생성에는 전달하지 마세요.

**enhance\_prompt** `boolean`

`true`이면 생성 전에 프롬프트를 자동 최적화합니다. 기본적으로 최적화하지 않고 원본 프롬프트를 사용합니다. 최종 영상 생성에는 전달하지 마세요.

**image\_with\_roles** `object[]`

각 항목은 `url`과 `role`을 포함합니다. 역할은 `first_frame`(첫 프레임), `last_frame`(마지막 프레임), `reference_image`(참조 이미지)입니다. 첫·마지막 프레임은 각각 최대 1장이고 마지막 프레임에는 첫 프레임이 필요합니다. 첫·마지막 프레임은 참조 미디어와 함께 사용할 수 없습니다.

`image_urls`와 `image_with_roles`는 함께 전달할 수 없습니다. 함께 보내면 제출 시 HTTP 400(`invalid_request_error`)을 반환하며 과금하지 않습니다. 별칭 `image`, `images`, `image_url`도 `image_urls`로 처리하므로 이 제한을 우회할 수 없습니다.

**image\_urls** `string[]`

참조 이미지 최대 30장. 형식·크기·파일 용량은 아래 미디어 요구 사항을 확인하세요.

`image_urls`와 `image_with_roles`는 함께 전달할 수 없습니다. 함께 보내면 제출 시 HTTP 400(`invalid_request_error`)을 반환하며 과금하지 않습니다. 별칭 `image`, `images`, `image_url`도 `image_urls`로 처리하므로 이 제한을 우회할 수 없습니다.

**first\_frame\_image** `string`

첫 프레임 이미지 주소. `image_with_roles`의 `first_frame` 역할과 같습니다.

**last\_frame\_image** `string`

마지막 프레임 이미지 주소. `image_with_roles`의 `last_frame` 역할과 같습니다. 첫 프레임도 필요합니다.

**video\_urls** `string[]`

참조 동영상 최대 10개. 공개 `http(s)` URL 또는 `asset://<미디어 ID>`를 지원하며 `data:` Base64는 지원하지 않습니다. 제출 시 아래 규칙으로 동영상 크기, 정확한 길이, 프레임률을 검사합니다.

과금 시에는 각 길이를 합산한 후 정수 초로 내림하며 이후 조정하지 않습니다. 이 내림은 개별 동영상 길이의 유효성 검사에는 사용하지 않습니다. 접근이나 길이 확인에 실패하면 HTTP 400(`input_video_probe_failed`)을 반환하며 과금하지 않습니다.

`auto` / `reference`: 2–15초, 허용 범위 `1.8 ≤ t ≤ 15.2`초. `edit` 원본 동영상: 4–30초, 허용 범위 `3.8 ≤ t < 30.2`초. 반올림하지 않은 정확한 길이로 검사합니다.

**audio\_urls** `string[]`

최대 10개, WAV / MP3. 각 2–15초 및 `≤ 15 MB`, 합계 30초 이하. ±0.2초 허용 오차로 개별 `1.8 ≤ t ≤ 15.2`초, 합계 `≤ 30.2`초를 허용합니다. 참조 이미지 또는 동영상이 필요합니다.

공개 `http(s)` URL 또는 `asset://<미디어 ID>`를 지원하며 `data:` Base64는 지원하지 않습니다. 오디오 길이는 제출 시 검사하고 조건 위반 시 동기 HTTP 400을 반환하며 과금하지 않습니다.

**draft** `boolean`

`true`이면 `480p` 초안을 생성합니다. 나머지 매개변수는 일반 생성 규칙을 따릅니다. 최종 영상 요청에는 이 필드를 전달하지 마세요.

동영상 편집(`edit`)은 초안을 생성할 수 없습니다.

**draft\_task\_id** `string`

성공한 초안의 `task_id`로 `1080p` 최종 영상을 생성합니다. 초안 생성 후 24시간 이내에 사용해야 합니다. 프롬프트·미디어·길이·화면비를 그대로 사용하므로 해당 필드를 다시 전달할 수 없습니다. 최종 영상 생성 시 `seed`, `audio`, 별칭 `generate_audio`도 전달할 수 없습니다.

## 미디어 주소 및 조합 제한

이미지·동영상·오디오는 공개 `http(s)` URL 또는 APIMart의 `asset://<미디어 ID>`를 지원합니다. 모두 `data:` Base64는 지원하지 않으므로 먼저 업로드하세요. 미디어 등록은 자동으로 처리되며 별도 API 호출이 필요 없습니다. 등록 실패 시 작업이 실패하고 환불됩니다.

| 미디어 | 요구 사항 |
| - | - |
| 참조 이미지 | 최대 30장; JPEG / PNG / WebP / BMP / TIFF / GIF / HEIC / HEIF; 화면비 0.4–2.5; 가로·세로 각각 300–6000픽셀; 장당 `< 30 MB`. |
| 참조 동영상 | 최대 10개; MP4 / MOV(H.264 / H.265; 오디오 트랙: AAC / MP3); 개당 `≤ 200 MB`. 크기·길이·프레임률 조건은 아래를 확인하세요. |
| 참조 오디오 | 최대 10개, WAV / MP3. 각 2–15초 및 `≤ 15 MB`, 합계 30초 이하. ±0.2초 허용 오차로 개별 `1.8 ≤ t ≤ 15.2`초, 합계 `≤ 30.2`초를 허용합니다. 참조 이미지 또는 동영상이 필요합니다. |

### 참조 동영상 검사 규칙

| 항목 | 요구 사항 |
| - | - |
| 가로·세로 | 가로·세로 각각 300–6000픽셀. |
| 픽셀 면적(가로 × 세로) | 409,600–8,295,044픽셀. |
| 화면비(가로 / 세로) | 0.4–2.5. |
| 개별 동영상 길이 | `auto` / `reference`: 2–15초, 허용 범위 `1.8 ≤ t ≤ 15.2`초. `edit` 원본 동영상: 4–30초, 허용 범위 `3.8 ≤ t < 30.2`초. 반올림하지 않은 정확한 길이로 검사합니다. |
| 프레임률 | 먼저 정수로 반올림한 후 24–60fps인지 검사합니다. 23.976과 59.94 모두 허용됩니다. |

동영상 크기, 픽셀 면적, 화면비, 정확한 길이와 프레임률 및 참조 오디오 길이를 제출 시 검사합니다. 조건 위반 시 동기 HTTP 400이며 과금하지 않습니다. 동영상 규격 오류는 `invalid_request_error`이며 실측값을 포함합니다. 짧은 변 480 이상·긴 변 4096 이하가 아닌 픽셀 면적으로 판단하세요.

크기만 보면 420×1000(420,000픽셀)은 허용됩니다. 720×480(345,600픽셀), 848×480(407,040픽셀), 4096×2160(8,847,360픽셀)은 면적 조건을 충족하지 못합니다. 길이·프레임률 등 다른 조건도 충족해야 합니다.

이미지 크기, 파일 용량, 인코딩은 생성 단계에서 검사합니다. 조건 위반 시 작업이 실패하고 자동 환불됩니다. 가능한 항목은 API 호출 전에 검사하세요.

### 미디어 조합 규칙

* `image_urls`와 `image_with_roles`는 함께 전달할 수 없습니다. 함께 보내면 제출 시 HTTP 400(`invalid_request_error`)을 반환하며 과금하지 않습니다. 별칭 `image`, `images`, `image_url`도 `image_urls`로 처리하므로 이 제한을 우회할 수 없습니다.
* 첫·마지막 프레임과 참조 이미지·동영상·오디오는 같은 요청에 포함할 수 없습니다.
* 첫·마지막 프레임은 각각 최대 1장입니다. 마지막 프레임에는 첫 프레임이 필요합니다.
* 참조 이미지 최대 30장, 동영상 최대 10개, 오디오 최대 10개이며 전체 미디어 합계는 최대 50개입니다.
* 조합 또는 개수 제한을 위반하면 제출 시 동기적으로 HTTP 400을 반환하며 과금하지 않습니다.
* `omni_reference_task_type: "edit"`에는 원본 동영상이 최소 1개 필요합니다(`3.8 ≤ t < 30.2`초). `duration` / `seconds`는 생략 또는 `-1`, `aspect_ratio` / `size`는 생략 또는 `adaptive`만 허용합니다. `draft: true`와 함께 사용하지 마세요. auto/reference에는 2–15초와 해당 허용 오차가 적용됩니다.

> [!WARNING]
>
> 다음 필드는 값이 `""`, `[]`, `false`, `null`이어도 존재하면 HTTP 400입니다. 필드 전체를 제거하세요: `negative_prompt`, `camera_fixed`, `camerafixed`, `extend_from_task_id`, `mask_url`, `video_list`, `element_list`, `multi_shot`, `tools`. `n`은 생략하거나 `1`만 전달하세요.

## 요청 예제

아래 미디어 URL은 예시입니다. 실제로 접근 가능한 미디어 주소로 바꾸세요.

### 첫·마지막 프레임

```json theme={null}
{
  "model": "apimart-zoe",
  "prompt": "빛의 연속성을 유지하며 첫 프레임에서 마지막 프레임으로 자연스럽게 전환한다",
  "image_with_roles": [
    {
      "url": "https://example.com/start.jpg",
      "role": "first_frame"
    },
    {
      "url": "https://example.com/end.jpg",
      "role": "last_frame"
    }
  ],
  "duration": 6
}
```

`first_frame_image`와 `last_frame_image`로도 지정할 수 있습니다. 같은 요청에 참조 이미지·동영상·오디오를 추가하지 마세요.

### 이미지·동영상·오디오 참조

```json theme={null}
{
  "model": "apimart-zoe",
  "prompt": "참조 이미지의 인물이 참조 동영상의 장면에서 자연스럽게 움직이고 배경 음악이 영상 리듬과 어우러진다",
  "image_urls": [
    "https://example.com/character.jpg"
  ],
  "video_urls": [
    "https://example.com/scene.mp4"
  ],
  "audio_urls": [
    "https://example.com/bgm.mp3"
  ],
  "duration": -1
}
```

`image_urls`의 이미지는 참조 이미지로 처리합니다. `duration: -1`이면 모델이 출력 길이를 결정합니다.

### 동영상 편집

`omni_reference_task_type: "edit"`에는 원본 동영상이 최소 1개 필요합니다(`3.8 ≤ t < 30.2`초). `duration` / `seconds`는 생략 또는 `-1`, `aspect_ratio` / `size`는 생략 또는 `adaptive`만 허용합니다. `draft: true`와 함께 사용하지 마세요. auto/reference에는 2–15초와 해당 허용 오차가 적용됩니다.

```json theme={null}
{
  "model": "apimart-zoe",
  "prompt": "원본 카메라 움직임과 구도를 유지하며 전체 영상을 흑백 고전 영화 스타일로 바꾸기",
  "video_urls": [
    "https://example.com/source_20s.mp4"
  ],
  "omni_reference_task_type": "edit"
}
```

편집에는 참조 동영상 요금이 적용됩니다. 출력 30초를 선차감하고 완료 후 실제 출력 길이를 정수 초로 반올림하여 정산합니다. 아래 공식에 따라 참조 동영상 길이도 포함해 차액을 조정합니다.

### 마지막 프레임, MOV 출력 및 프롬프트 최적화

```json theme={null}
{
  "model": "apimart-zoe",
  "prompt": "창가의 주황색 아기 고양이가 카메라를 바라보고 옆에서 햇빛이 들어오며 카메라가 천천히 다가간다",
  "duration": 5,
  "return_last_frame": true,
  "output_format": "mov",
  "enhance_prompt": true
}
```

## 초안 → 최종 영상

1. `draft: true`로 초안을 제출합니다. `resolution`을 생략하면 `480p`이며 명시하는 경우에도 `480p`만 지원합니다.

```json theme={null}
{
  "model": "apimart-zoe",
  "prompt": "창가의 주황색 아기 고양이가 카메라를 바라보고 옆에서 햇빛이 들어오며 카메라가 천천히 다가간다",
  "draft": true
}
```

2. 초안이 성공하면 해당 `task_id`로 최종 영상을 요청합니다. `model`과 `draft_task_id`만 필요합니다. `resolution`을 명시하려면 `1080p`를 사용하세요.

```json theme={null}
{
  "model": "apimart-zoe",
  "draft_task_id": "task_01KZOEEXAMPLE"
}
```

> [!WARNING]
>
> 최종 영상은 초안의 프롬프트, 미디어, 길이, 화면비, 시드 및 오디오 설정을 상속합니다. `model`, `draft_task_id`, 선택적 `resolution: "1080p"`, `nsfw_check` / `webhook` 같은 공통 필드만 전달하세요. 다음 생성 필드는 없어야 하며 빈 문자열·빈 배열·`false`·`null`도 HTTP 400입니다: `prompt`, `image_urls`, `image_with_roles`, `image`, `images`, `image_url`, `first_frame_image`, `last_frame_image`, `video_urls`, `audio_urls`, `duration`, `seconds`, `aspect_ratio`, `size`, `seed`, `audio`, `generate_audio`, `draft`, `omni_reference_task_type`, `return_last_frame`, `output_format`, `response_format`, `enhance_prompt`. 초안 생성 후 24시간 이내에 사용하며 두 생성은 별도 과금합니다.

## 작업 및 결과 조회

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

제출 응답의 `data`는 배열이고 조회 응답의 `data`는 작업 객체입니다. `data.status`는 `pending`(대기), `processing`(생성 중), `completed`(성공), `failed`(실패)입니다. 성공 시 `data.result.videos[].url` 배열에서 주소를 읽습니다. 예: `data.result.videos[0].url[0]`. 동영상은 APIMart 저장소로 복사됩니다. 아래는 성공한 조회의 주요 필드만 보여 줍니다.

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KZOEEXAMPLE",
    "status": "completed",
    "result": {
      "videos": [
        {
          "url": [
            "https://example.com/generated-video.mp4"
          ],
          "expires_at": 1794475442
        }
      ],
      "last_frame_url": "https://example.com/generated-last-frame.png"
    },
    "progress": 100,
    "completed": 1794389042
  }
}
```

작업 실패 시 `data.error.message`에서 원인을 확인하세요. 차감 금액은 자동 환불됩니다.

| 필드 | 설명 |
| - | - |
| `data.progress` | 작업 진행률, 0–100. |
| `data.result.videos[].url` | APIMart 저장소로 복사된 동영상 주소 배열. |
| `data.result.videos[].expires_at` | 주소는 작업 완료 후 24시간 동안 유효합니다. 바로 다운로드하세요. |
| `data.result.last_frame_url` | APIMart 스토리지에 저장된 PNG 마지막 프레임 URL. 요청에 `return_last_frame: true`가 있고 작업이 성공한 경우에만 반환됩니다. |
| `data.error.message` | 실패 원인. `failed`인 경우에만 반환됩니다. |
| `data.error.code` | 실패 시 문자열 `task_failed`. |
| `data.cost` | 이번 작업 비용. 실패한 작업은 선차감액이 환불되며 0입니다. |

## 과금 규칙

출력 해상도와 참조 동영상 유무에 따라 초 단위로 과금합니다. 단가와 계정 할인은 [가격 페이지](https://apimart.ai/pricing)를 확인하세요. `D`는 과금에 사용하는 출력 길이(초)입니다.

| 경우 | 출력 과금 길이 D |
| - | - |
| 일반 생성: `duration: 4–30` 지정 또는 생략(기본 5) | 요청한 초로 과금하며 완성된 영상 길이에 따라 조정하지 않습니다. |
| `duration: -1` / 동영상 편집 `edit` | 30초분을 선차감하고 완료 후 실제 길이를 정수 초로 반올림하여 차액을 정산합니다. |
| 최종 영상 | 초안 길이를 따릅니다. 초안이 `duration: -1`이면 초안의 실제 완성 길이를 기준으로 하며 최종 영상 길이로 다시 조정하지 않습니다. |

* 참조 동영상 총길이 `R`: 제출 시 각 길이를 확인하고 합산한 다음 정수 초로 내림합니다. 이후에는 조정하지 않습니다.
* 참조 동영상이 없으면 과금 초 = `D`. 있으면 과금 초 = `D + max(R, ceil(D × 2/3))`. `ceil`은 정수로 올림합니다. 참조 동영상이 있는 경우의 단가를 사용합니다.
* 예: 8초 요청은 결과가 8.2초여도 `D = 8`입니다. 자동 길이 결과가 8.5초면 `D = 9`입니다. 참조 영상 2.8초와 3.8초는 합계 6.6초를 내림해 `R = 6`입니다.
* 초안은 `480p`, 최종 영상은 `1080p`로 각각 과금합니다. 초안에 참조 동영상이 있으면 최종 영상에도 원래 참조 길이를 포함하며 재업로드할 필요는 없습니다.
* 제출 실패는 과금하지 않으며 작업 실패 시 자동 환불됩니다.

## 일반적인 오류

제출 실패 시 `error` 객체를 반환합니다. 설명은 `error.message`, 문자열 오류 코드는 `error.code`이며 HTTP 상태 코드와 다릅니다. 제출 실패는 과금하지 않습니다.

| HTTP | `error.code` | 원인 및 해결 방법 |
| - | - | - |
| 400 | `invalid_request_error` | 길이·해상도·화면비·미디어 개수와 조합·지원하지 않는 매개변수·초안/최종 영상 제한을 확인하세요. `draft_task_id`가 없거나 초안이 아니거나 미완료이거나 생성 후 24시간을 넘긴 경우도 해당합니다. 참조 동영상 크기·정확한 길이·프레임률 위반 및 `image_urls`(별칭 포함)와 `image_with_roles` 혼용도 해당합니다. 동영상 검사 오류에 실측값이 포함됩니다. 참조 오디오 길이, 작업 유형과 편집 제한, `output_format`, 오디오 별칭 값 일치 및 금지 필드의 존재 여부도 확인하세요. |
| 400 | `nsfw_content_detected` | 콘텐츠 심사 거부. `error.message`에 감지 범주가 포함됩니다. 심사 거부로 표시하고 내용을 수정한 후 다시 제출하세요. 과금하지 않습니다. |
| 400 | `input_video_probe_failed` | 참조 동영상에 접근하거나 길이를 확인할 수 없습니다. 주소와 내용을 확인하세요. |
| 402 | `payment_required` | 잔액 부족. 자동 길이는 30초분을 선차감합니다. |
| 503 | `draft_channel_unavailable` / `draft_task_unavailable` | 초안 생성 채널을 사용할 수 없거나 일시적으로 초안 조회에 실패했습니다. 나중에 재시도하거나 초안을 새로 생성하세요. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.