> ## 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` が返されます。[タスクステータス取得](/ja/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 秒ごとにポーリングすることをおすすめします。1 つのタスクは通常約 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` に失敗理由を返します。よくある原因には、上流の一時的なクォータ不足、コンテンツ審査不通過、上流タイムアウトがあります。