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

# Gemini Omni 1.1 Flash 비디오 생성

>  - Google 공식 Gemini Omni 1.1 Flash 올인원 멀티모달 비디오 생성 모델
- 텍스트-비디오, 이미지-비디오, 다중 피사체 참조, 시작·종료 프레임 보간, 비디오 편집 및 연장 지원
- 360p / 720p / 1080p / 4K, 24fps, 3~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": "gemini-omni-1.1-flash",
      "prompt": "A marble rolling fast on a chain reaction style track, continuous smooth shot.",
      "aspect_ratio": "16:9",
      "resolution": "1080p"
    }'
  ```

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

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

  payload = {
      "model": "gemini-omni-1.1-flash",
      "prompt": "A marble rolling fast on a chain reaction style track, continuous smooth shot.",
      "aspect_ratio": "16:9",
      "resolution": "1080p"
  }

  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: "gemini-omni-1.1-flash",
    prompt: "A marble rolling fast on a chain reaction style track, continuous smooth shot.",
    aspect_ratio: "16:9",
    resolution: "1080p"
  };

  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":        "gemini-omni-1.1-flash",
          "prompt":       "A marble rolling fast on a chain reaction style track, continuous smooth shot.",
          "aspect_ratio": "16:9",
          "resolution":   "1080p",
      }

      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>
  모든 API는 Bearer Token 인증이 필요합니다.

  API 키 받기:

  [API 키 관리 페이지](https://apimart.ai/keys)에서 API 키를 발급받으세요.

  사용할 때 요청 헤더에 다음을 추가하세요:

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

## 요청 매개변수

<ParamField body="model" type="string" required>
  비디오 생성 모델 이름입니다. `gemini-omni-1.1-flash`로 고정됩니다.
</ParamField>

<ParamField body="prompt" type="string">
  텍스트 지시문입니다. 텍스트-비디오에서는 장면을 설명하고, 이미지-비디오·비디오 편집·연장에서는 동작, 스타일 또는 편집 요구 사항을 설명합니다.

  <Note>
    `prompt` 또는 미디어(`image_urls`, 시작/종료 프레임 이미지, `video_urls`) 중 하나 이상을 제공해야 합니다.
  </Note>
</ParamField>

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

  선택 가능한 값:

  * `360p`
  * `720p`(기본값)
  * `1080p`
  * `4k`

  `2160p`는 `4k`로 처리됩니다. 해상도에 따라 작업의 선차감 보증금 구간과 주요 비디오 출력 비용이 결정됩니다.

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

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

  지원 값:

  * `16:9` - 가로(기본값)
  * `9:16` - 세로

  그 외 값은 `16:9`로 처리됩니다.

  <Warning>
    `video_urls`를 전달하면 출력은 일반적으로 입력 비디오의 화면 비율을 따르므로 `aspect_ratio`가 적용되지 않을 수 있습니다.
  </Warning>
</ParamField>

<ParamField body="image_urls" type="array<string>">
  참조 이미지 배열입니다. 공개적으로 접근 가능한 HTTP/HTTPS URL만 지원합니다.

  * 이미지 1장 전달: 기본적으로 비디오의 시작 프레임으로 사용
  * 여러 이미지 전달: 다중 피사체 또는 스타일 참조로 사용되며, 각 이미지의 용도와 관계를 `prompt`에 설명하세요

  <Warning>
    `image_urls`와 시작/종료 프레임 이미지는 합계 최대 10장까지 가능합니다.
  </Warning>
</ParamField>

<ParamField body="first_frame_image" type="string">
  시작 프레임 이미지입니다. 공개적으로 접근 가능한 HTTP/HTTPS URL만 지원합니다.

  * 단독 전달: 해당 이미지를 비디오의 시작 프레임으로 사용
  * `last_frame_image`와 함께 전달: 시작 프레임에서 종료 프레임으로 부드럽게 전환되는 비디오 생성
</ParamField>

<ParamField body="last_frame_image" type="string">
  종료 프레임 이미지입니다. 공개적으로 접근 가능한 HTTP/HTTPS URL만 지원하며 `first_frame_image`와 함께 전달해야 합니다.

  <Warning>
    `last_frame_image`만 전달하면 `invalid_frame_images` 오류가 반환됩니다. 시작/종료 프레임 이미지는 같은 비율을 사용하고 `aspect_ratio`와 일치시키는 것이 좋습니다.
  </Warning>
</ParamField>

<Note>
  시작 프레임 또는 시작·종료 프레임 생성에서 다음 두 방식은 같은 효과를 냅니다. **둘 중 하나만 선택하고 동시에 전달하지 마세요**:

  * `first_frame_image` / `last_frame_image` 사용
  * `image_with_roles`를 사용하고 `role`을 `first_frame` / `last_frame`으로 설정
</Note>

<ParamField body="image_with_roles" type="array<object>">
  역할이 지정된 이미지 배열입니다. `first_frame_image` / `last_frame_image`와 동일한 방식으로 사용할 수 있으며 참조 이미지 선언에도 사용할 수 있습니다.

  <Expandable title="image_with_roles 요소">
    <ParamField body="url" type="string" required>
      공개적으로 접근 가능한 이미지 HTTP/HTTPS URL입니다.
    </ParamField>

    <ParamField body="role" type="string" required>
      이미지 역할:

      * `first_frame`: 시작 프레임
      * `last_frame`: 종료 프레임. 시작 프레임도 있어야 합니다
      * `reference`: 참조 이미지. 시작/종료 프레임 이외의 역할도 참조 이미지로 처리됩니다
    </ParamField>
  </Expandable>

  예시:

  ```json theme={null}
  [
    {"url": "https://example.com/start.jpg", "role": "first_frame"},
    {"url": "https://example.com/end.jpg", "role": "last_frame"}
  ]
  ```

  <Note>
    `image_urls`도 전달하면 참조 이미지는 `image_urls`가 우선하며 `image_with_roles`의 참조 이미지와 합쳐지지 않습니다. 실제 사용되는 모든 이미지는 시작/종료 프레임을 포함해 합계 최대 10장입니다.
  </Note>
</ParamField>

<ParamField body="video_urls" type="array<string>">
  편집하거나 연장할 비디오 배열입니다. 현재 최대 1개만 전달할 수 있으며 길이는 10초 이하여야 합니다.

  공개적으로 접근 가능한 HTTP/HTTPS 비디오 직접 링크만 지원합니다. YouTube 링크는 지원하지 않습니다.

  <Warning>
    `video_urls`와 `extend_from_task_id`는 상호 배타적입니다. 둘 중 하나만 제공하세요.
  </Warning>
</ParamField>

<ParamField body="metadata" type="object">
  생성 의도를 명시적으로 지정하는 추가 매개변수 객체입니다.

  <Expandable title="metadata 필드">
    <ParamField body="task" type="string">
      선택 가능한 작업 유형:

      * `text_to_video`: 텍스트-비디오
      * `image_to_video`: 이미지-비디오
      * `reference_to_video`: 참조 소재-비디오
      * `edit`: 비디오 편집
      * `extend`: 비디오 연장

      생략하면 시스템이 입력 내용과 프롬프트를 기준으로 자동 판단합니다.
    </ParamField>
  </Expandable>

  <Note>
    시작·종료 프레임 보간에서는 모델이 작업 유형을 자동으로 추론하며 플랫폼은 `metadata.task`를 전달하지 않습니다.
  </Note>
</ParamField>

<ParamField body="extend_from_task_id" type="string">
  이전 생성 작업의 로컬 `task_id`입니다. 이전 비디오를 다시 업로드하지 않고 대화형 편집이나 추가 연장에 사용합니다.

  참조 작업은 현재 사용자 소유이고 성공 상태이며 Gemini Omni 모델 작업이어야 합니다.

  <Warning>
    `extend_from_task_id`와 `video_urls`는 상호 배타적입니다. 둘 중 하나만 제공하세요.
  </Warning>
</ParamField>

<Warning>
  이 모델에는 `duration` 매개변수가 없습니다. 각 출력 길이는 콘텐츠에 따라 모델이 자동으로 결정하며 일반적으로 3\~10초입니다. 속도를 제어하려면 `prompt`에 자연어나 시간 구간으로 설명하세요.
</Warning>

## 응답

<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초마다 폴링하고 상태가 `completed` 또는 `failed`가 되면 중지하세요. 전체 클라이언트 제한 시간은 10분을 권장합니다.

### 성공 결과 예시

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KS1H7ZYSJWH1N779S2FSHTKA",
    "status": "completed",
    "progress": 100,
    "cost": 1.52,
    "credits_cost": 15.2,
    "result": {
      "videos": [
        {
          "url": ["https://cdn.example.com/gemini_omni_xxx.mp4"],
          "expires_at": 1788518400
        }
      ]
    }
  }
}
```

## 사용 사례

### 사용 사례 1: 텍스트-비디오(4K)

```json theme={null}
{
  "model": "gemini-omni-1.1-flash",
  "prompt": "a blue butterfly landing on a flower, macro, soft light, no dialogue",
  "aspect_ratio": "9:16",
  "resolution": "4k"
}
```

### 사용 사례 2: 시작·종료 프레임 보간

```json theme={null}
{
  "model": "gemini-omni-1.1-flash",
  "prompt": "smooth transition, camera slowly pushes in",
  "first_frame_image": "https://example.com/start.jpg",
  "last_frame_image": "https://example.com/end.jpg",
  "resolution": "720p"
}
```

### 사용 사례 3: 다중 피사체 참조

```json theme={null}
{
  "model": "gemini-omni-1.1-flash",
  "prompt": "the cat playfully bats at the ball of yarn",
  "image_urls": [
    "https://example.com/cat.png",
    "https://example.com/yarn.png"
  ],
  "resolution": "720p"
}
```

### 사용 사례 4: 이미지 역할로 시작·종료 프레임 선언

```json theme={null}
{
  "model": "gemini-omni-1.1-flash",
  "prompt": "a smooth cinematic transition from sunrise to a starry night",
  "image_with_roles": [
    {"url": "https://example.com/sunrise.jpg", "role": "first_frame"},
    {"url": "https://example.com/night.jpg", "role": "last_frame"}
  ],
  "resolution": "1080p"
}
```

### 사용 사례 5: 비디오 편집

```json theme={null}
{
  "model": "gemini-omni-1.1-flash",
  "prompt": "Make the violin invisible. Keep everything else the same.",
  "video_urls": ["https://example.com/clip.mp4"]
}
```

비디오 편집에는 짧고 명확한 프롬프트를 권장합니다. 특정 부분만 변경하려면 나머지 화면의 일관성을 유지하도록 `Keep everything else the same`을 추가하세요.

### 사용 사례 6: 대화형 연장

```json theme={null}
{
  "model": "gemini-omni-1.1-flash",
  "prompt": "Extend this video: the camera pans across the mountains.",
  "extend_from_task_id": "task_01AAA"
}
```