# 영상 생성 API

> LMU AI 영상 생성 API 개요: Seedance와 Wan 중 선택하는 방법과 인증, 비동기 작업, 과금, 동시 실행 제한, 오류 코드에 관한 공통 규칙을 안내합니다.

URL: https://docs.lmuai.ai/ko/docs/api/video-generation



LMU AI는 두 종류의 **비동기** 영상 생성 API를 제공하며, 둘 다 각 벤더의 **네이티브 프로토콜**을 사용합니다. 공식 SDK나 curl 명령의 주소를 LMU AI 주소로, 키를 LMU AI API 키로 바꾸기만 하면 요청 본문은 그대로 사용할 수 있습니다. 이 페이지는 개요 페이지입니다. 아래 표에서 API를 선택한 뒤 해당 제공업체 페이지를 참고하세요. 두 제공업체에 공통으로 적용되는 규칙(인증, 과금, 동시 실행 제한, 오류 코드)은 이 페이지에서 설명합니다.

<Callout type="info" title="Base URL">
  ```text
  https://api.lmuai.ai
  ```

  | 제공업체                      | 작업 생성                                                         | 작업 조회                                         | 문서                                                |
  | ------------------------- | ------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------- |
  | Seedance (Volcengine Ark) | `POST /api/v3/contents/generations/tasks`                     | `GET /api/v3/contents/generations/tasks/{id}` | [Seedance 영상 생성 API](/ko/docs/api/seedance-video) |
  | Wan (Alibaba DashScope)   | `POST /api/v1/services/aigc/video-generation/video-synthesis` | `GET /api/v1/tasks/{task_id}`                 | [Wan 영상 생성 API](/ko/docs/api/wan-video)           |
</Callout>

<Callout type="warn" title="그룹에 영상 생성이 활성화되어 있어야 합니다">
  API 키의 그룹에 "영상 생성"이 활성화되어 있어야 하며, 그렇지 않으면 호출 시 `403`이 반환됩니다. 실제로 호출할 수 있는 모델은 API 키에 따라 다르며, `GET /v1/models`로 확인할 수 있습니다.
</Callout>

## 1. 두 API 중 선택하기 [#compare]

|           | Seedance (Volcengine Ark)                                   | Wan (Alibaba DashScope)                                     |
| --------- | ----------------------------------------------------------- | ----------------------------------------------------------- |
| 예시 모델     | `seedance-2.5`                                              | `wan3.0-video`                                              |
| 과금 방식     | 출력 Token 기준                                                 | "실제 초 수 × 해상도 등급 단가" 기준                                     |
| 해상도 값     | `480p` / `720p` / `1080p` (소문자)                             | `480P` / `720P` / `1080P` (대문자), 기본값 `1080P`                |
| 작업 상태     | `queued` → `running` → `succeeded` / `failed` / `cancelled` | `PENDING` → `RUNNING` → `SUCCEEDED` / `FAILED` / `CANCELED` |
| 영상 URL 필드 | `content.video_url`                                         | `output.video_url`                                          |
| 작업 취소     | 대기 중(`queued`)인 작업은 취소 가능                                   | 취소 엔드포인트 없음. 제출된 작업은 항상 완료될 때까지 실행됨                         |

모델 이름은 그룹에 활성화된 이름과 **정확히** 일치해야 합니다(대소문자 구분). 두 API는 필드 이름이 비슷하지만 대소문자와 경로가 다르므로, 예시를 복사할 때 혼동하지 않도록 주의하세요.

## 2. 인증 [#auth]

모든 요청의 헤더에 API 키를 포함하세요.

```http
Authorization: Bearer YOUR_API_KEY
```

API 키를 브라우저 프런트엔드 코드, 공개 저장소, URL 쿼리 문자열 또는 로그에 넣지 마세요. API는 자체 서버에서 호출하세요.

## 3. 비동기 작업 흐름 [#flow]

1. **생성**: `POST`는 작업 id만 반환하며, 영상이 완성될 때까지 기다리지 않습니다.
2. **폴링**: 작업이 최종 상태(성공 / 실패 / 취소)에 도달할 때까지 약 10초마다 `GET`으로 작업을 조회합니다.
3. **참조 이미지**: API 호출 시에는 공개적으로 접근 가능한 이미지 URL(JPG / PNG / WebP)을 전달해야 합니다. 콘솔의 영상 생성 페이지에서는 로컬 이미지 업로드가 가능합니다.
4. **다운로드**: 성공하면 응답에서 영상 링크를 가져옵니다. 업스트림 링크는 **24시간 동안 유효**하므로 빠르게 다운로드하세요. 플랫폼은 완성된 각 영상의 사본을 보관하며, 콘솔의 영상 작업 페이지에서 재생하고 다운로드할 수 있습니다.

<Callout type="info" title="폴링을 중단해도 과금은 정산됩니다">
  제출 후 플랫폼이 백그라운드에서 작업을 추적하므로, 조회를 중단하더라도 정상적으로 정산됩니다. 실패하거나 취소된 작업은 과금되지 않습니다.
</Callout>

작업 생성 및 폴링의 전체 예시는 [Seedance](/ko/docs/api/seedance-video#poll-example) 및 [Wan](/ko/docs/api/wan-video#poll-example) 페이지를 참고하세요.

## 4. 과금 및 워터마크 [#billing]

* 작업 생성 시 예상 금액이 동결됩니다. 잔액이 부족하면 요청이 즉시 거부되며(`402`) 영상은 생성되지 않습니다.
* 성공 시 실제 사용량에 따라 한 번 정산되며, 초과 동결된 금액은 자동으로 반환됩니다. 실패하거나 취소된 작업은 전액 환불되며 과금되지 않습니다.
* Seedance는 출력 Token 기준으로, Wan은 "실제 초 수 × 해상도 등급 단가" 기준으로 과금됩니다.
* 완성된 영상에는 플랫폼의 "AI 생성" 라벨이 표시되며, 클라이언트에서 끌 수 없습니다.

## 5. 동시 실행 제한 [#limits]

각 사용자와 각 API 키는 동시에 최대 **5**개의 작업을 생성할 수 있습니다. 이를 초과하면 요청에 `429`와 함께 `Retry-After` 헤더(약 60초)가 반환됩니다. 대기한 후 다시 시도하세요.

## 6. 오류 코드 [#errors]

| HTTP                  | 의미                                            | 조치 방법                                |
| --------------------- | --------------------------------------------- | ------------------------------------ |
| `401`                 | API 키가 유효하지 않거나 비활성화됨                         | API 키를 확인하세요                         |
| `402`                 | 예상 금액을 동결하기에 잔액 또는 할당량이 부족함                   | 충전 후 다시 시도하세요                        |
| `403`                 | 그룹에 영상 생성이 활성화되어 있지 않거나, 그룹에서 해당 모델을 사용할 수 없음 | 영상 생성을 지원하는 API 키를 사용하세요             |
| `404 model_not_found` | 모델을 아직 사용할 수 없음(모델 이름 오타로도 발생)                | `GET /v1/models`가 반환하는 정확한 이름을 사용하세요 |
| `409`                 | 작업이 이미 생성을 시작하여 취소할 수 없음(Seedance 취소 엔드포인트)   | 작업이 완료될 때까지 기다리세요                    |
| `429`                 | 진행 중인 작업 수가 한도에 도달함                           | `Retry-After`에 따라 대기한 후 다시 시도하세요     |

일반 오류는 [오류 코드](/ko/docs/guide/errors)를 참고하세요.

## 7. 제공업체 페이지 [#providers]

* [Seedance 영상 생성 API](/ko/docs/api/seedance-video): 작업 생성, 조회, 목록 조회 및 취소와 함께 파라미터, 첫 프레임 참조 이미지에 관한 참고 사항, 전체 폴링 예시를 제공합니다.
* [Wan 영상 생성 API](/ko/docs/api/wan-video): 작업 생성 및 조회와 함께 파라미터와 전체 폴링 예시를 제공합니다.