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

# Omni-Flash-Ext 비디오 생성

>  - Omni-Flash-Ext 통합 비디오 생성 모델
- 텍스트-비디오, 단일 이미지-비디오, 참조 비디오, 3장 참조 이미지 융합 지원
- 720p/1080p/4k 해상도와 4/6/8/10초 길이 지원
- 비동기 작업 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": "Omni-Flash-Ext",
      "prompt": "a girl is dancing happily in a sunny garden",
      "duration": 10,
      "resolution": "1080p",
      "aspect_ratio": "9:16"
    }'
  ```

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

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

  payload = {
      "model": "Omni-Flash-Ext",
      "prompt": "a girl is dancing happily in a sunny garden",
      "duration": 10,
      "resolution": "1080p",
      "aspect_ratio": "9:16"
  }

  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: "Omni-Flash-Ext",
    prompt: "a girl is dancing happily in a sunny garden",
    duration: 10,
    resolution: "1080p",
    aspect_ratio: "9:16"
  };

  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));
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "io/ioutil"
      "net/http"
  )

  func main() {
      url := "https://api.apimart.ai/v1/videos/generations"

      payload := map[string]interface{}{
          "model":        "Omni-Flash-Ext",
          "prompt":       "a girl is dancing happily in a sunny garden",
          "duration":     10,
          "resolution":   "1080p",
          "aspect_ratio": "9:16",
      }

      jsonData, _ := json.Marshal(payload)

      req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
      req.Header.Set("Authorization", "Bearer <token>")
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          panic(err)
      }
      defer resp.Body.Close()

      body, _ := ioutil.ReadAll(resp.Body)
      fmt.Println(string(body))
  }
  ```
</RequestExample>

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

  ```json 400 theme={null}
  {
    "error": {
      "code": 400,
      "message": "요청 파라미터가 올바르지 않습니다",
      "type": "invalid_request_error"
    }
  }
  ```

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

  ```json 402 theme={null}
  {
    "error": {
      "code": 402,
      "message": "계정 잔액이 부족합니다. 충전 후 다시 시도하세요",
      "type": "payment_required"
    }
  }
  ```

  ```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>
  비디오 생성 모델 이름입니다. `Omni-Flash-Ext`로 고정됩니다.
</ParamField>

<ParamField body="prompt" type="string" required>
  비디오 내용 설명입니다. 장면, 인물, 동작, 환경, 카메라 움직임, 화면 스타일, 오디오 힌트를 자세히 작성하는 것을 권장합니다.

  예: `"a girl is dancing happily in a sunny garden"`
</ParamField>

<ParamField body="duration" type="integer" default="6">
  비디오 길이입니다. 단위는 초입니다.

  지원 값: `4`, `6`, `8`, `10`.

  <Warning>
    `5`, `7` 등 다른 값을 전달하면 `invalid_duration` 오류가 반환됩니다.
  </Warning>

  <Warning>
    참조 비디오를 업로드할 때는 `duration`을 전달할 필요가 없습니다. `duration`과 `video_urls`는 동시에 전달할 수 없습니다.
  </Warning>
</ParamField>

<ParamField body="resolution" type="string" default="720p">
  비디오 해상도입니다. 대소문자를 구분하지 않습니다.

  지원 값:

  * `720p`
  * `1080p`
  * `4k`

  <Warning>
    다른 해상도를 전달하면 `invalid_resolution` 오류가 반환됩니다.
  </Warning>
</ParamField>

<ParamField body="aspect_ratio" type="string" default="16:9">
  비디오 화면 비율입니다. 가로 또는 세로 출력을 제어합니다.

  자주 사용하는 값:

  * `16:9` - 가로
  * `9:16` - 세로

  기본값: `16:9`
</ParamField>

<ParamField body="size" type="string">
  호환 필드입니다. `aspect_ratio`와 같은 의미입니다. 둘 다 전달하는 경우 같은 값으로 유지하는 것을 권장합니다.
</ParamField>

<ParamField body="generation_type" type="string">
  생성 유형으로, 이미지의 사용 방식을 지정합니다.

  가능한 값:

  * `frame` - 시작 프레임 모드. `image_urls`에는 이미지 1장만 업로드할 수 있으며, 비디오의 시작 프레임으로 사용됩니다.
  * `reference` - 참조 모드. `image_urls`에는 이미지 1장 또는 3장을 업로드할 수 있으며, 참조 이미지로 사용됩니다.

  <Warning>
    `generation_type`이 `frame`인 경우 `image_urls`는 1장만 지원하며, 다른 개수를 전달하면 `unsupported_image_count` 오류가 반환됩니다.
  </Warning>
</ParamField>

<ParamField body="image_urls" type="array<url>">
  참조 이미지 URL 배열입니다. `generation_type`에 따라 생략하거나, 1장 또는 3장을 전달할 수 있습니다:

  * 생략 또는 빈 배열: 텍스트-비디오
  * 1장: 단일 이미지-비디오
  * 3장: 참조 이미지 융합(`generation_type`이 `reference`일 때만 지원)

  `generation_type`과의 관계:

  * `generation_type`이 `frame`: 이미지 1장만 업로드할 수 있습니다.
  * `generation_type`이 `reference`: 이미지 1장 또는 3장을 업로드할 수 있습니다.

  공개적으로 접근 가능한 이미지 URL만 지원합니다.

  <Warning>
    2장 이미지로 시작 프레임 + 끝 프레임을 지정하는 모드는 지원하지 않습니다. 2장을 전달하면 `unsupported_image_count` 오류가 반환됩니다. 4장 이상은 충분히 검증되지 않았으므로 권장하지 않습니다.
  </Warning>
</ParamField>

<ParamField body="video_urls" type="array<url>">
  참조 비디오 URL 배열입니다. 생략하거나 참조 비디오 1개를 전달할 수 있습니다.

  공개적으로 접근 가능한 HTTP/HTTPS 비디오 URL만 지원합니다. `image_urls`와 함께 전달할 수 있으며, 이미지는 인물 또는 구도 참조로, 비디오는 움직임 참조로 사용됩니다.

  <Warning>
    `Omni-Flash-Ext`는 참조 비디오를 0개 또는 1개만 지원합니다. 2개 이상 전달하면 `unsupported_video_count` 오류가 반환됩니다.
  </Warning>

  <Warning>
    `video_urls`를 전달할 때는 `duration`을 전달할 필요가 없습니다. `video_urls`와 `duration`은 동시에 전달할 수 없습니다.
  </Warning>
</ParamField>

## 응답

<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) API로 진행 상황과 결과를 조회하세요.

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

제출 후 5-10초 기다린 뒤 처음 조회하고, 이후 5-10초마다 폴링하는 것을 권장합니다. 단일 작업은 일반적으로 약 3-5분 안에 완료됩니다.

### 성공 결과 예시

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KS1H7ZYSJWH1N779S2FSHTKA",
    "status": "completed",
    "progress": 100,
    "created": 1779246294,
    "completed": 1779246534,
    "actual_time": 240,
    "estimated_time": 600,
    "cost": 0.4,
    "credits_cost": 4,
    "result": {
      "videos": [
        {
          "url": ["https://cdn.example.com/videos/abc.mp4"],
          "expires_at": 1779332760
        }
      ]
    }
  }
}
```

### 실패 결과 예시

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KS1H7ZYSJWH1N779S2FSHTKA",
    "status": "failed",
    "progress": 100,
    "created": 1779246294,
    "completed": 1779246534,
    "actual_time": 240,
    "estimated_time": 600,
    "cost": 0,
    "credits_cost": 0,
    "error": {
      "message": "invalid duration 7, must be one of 4/6/8/10",
      "code": "task_failed"
    }
  }
}
```

## 사용 사례

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

```json theme={null}
{
  "model": "Omni-Flash-Ext",
  "prompt": "a beautiful sunset over the ocean with seagulls flying",
  "duration": 6,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}
```

### 시나리오 2: 단일 이미지-비디오

```json theme={null}
{
  "model": "Omni-Flash-Ext",
  "prompt": "make the character smile and slowly turn around, cinematic camera motion",
  "duration": 6,
  "resolution": "1080p",
  "aspect_ratio": "9:16",
  "image_urls": ["https://example.com/character.jpg"]
}
```

### 시나리오 3: 3장 참조 이미지 융합

```json theme={null}
{
  "model": "Omni-Flash-Ext",
  "prompt": "a creative scene combining these elements with smooth camera motion",
  "duration": 10,
  "resolution": "1080p",
  "aspect_ratio": "9:16",
  "image_urls": [
    "https://example.com/scene.jpg",
    "https://example.com/character.jpg",
    "https://example.com/product.jpg"
  ]
}
```

### 시나리오 4: 4K 짧은 비디오

```json theme={null}
{
  "model": "Omni-Flash-Ext",
  "prompt": "close-up of a hummingbird hovering in front of a red flower",
  "duration": 4,
  "resolution": "4k",
  "aspect_ratio": "16:9"
}
```

### 시나리오 5: 참조 비디오 생성

```json theme={null}
{
  "model": "Omni-Flash-Ext",
  "prompt": "the same scene but at night with neon lights",
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "video_urls": ["https://example.com/reference.mp4"]
}
```

## 오류 코드

| HTTP | 오류 유형                     | 의미                                                                    | 해결 방법                      |
| ---- | ------------------------- | --------------------------------------------------------------------- | -------------------------- |
| 400  | `invalid_request_error`   | `model`이 `Omni-Flash-Ext`가 아니거나, `prompt`가 비어 있거나, JSON 형식이 올바르지 않습니다 | 요청 본문을 확인하세요               |
| 400  | `invalid_duration`        | `duration`이 `4`, `6`, `8`, `10` 중 하나가 아닙니다                            | 지원되는 길이로 변경하세요             |
| 400  | `invalid_resolution`      | `resolution`이 `720p`, `1080p`, `4k` 중 하나가 아닙니다                        | 지원되는 해상도로 변경하세요            |
| 400  | `unsupported_image_count` | `image_urls` 개수가 지원되지 않습니다. 2장을 전달할 때 자주 발생합니다                        | 0장, 1장 또는 3장으로 변경하세요       |
| 400  | `unsupported_video_count` | `video_urls` 개수가 지원되지 않습니다. 2개 이상 전달할 때 자주 발생합니다                      | 참조 비디오를 0개 또는 1개로 변경하세요    |
| 401  | `authentication_error`    | Token이 유효하지 않습니다                                                      | Bearer Token을 확인하세요        |
| 402  | `payment_required`        | 잔액이 부족합니다                                                             | 충전 후 다시 시도하세요              |
| 429  | `rate_limit_error`        | 요청 제한에 도달했습니다                                                         | 동시 요청 수를 낮추거나 나중에 다시 시도하세요 |

작업이 실패하면 작업 상태 API가 `data.error`에 실패 사유를 반환합니다. 일반적인 원인은 업스트림 할당량 일시 부족, 콘텐츠 심사 실패, 업스트림 타임아웃입니다.