> ## 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/ja/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 画像として追加返却し、URL は `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` を含みます。`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 ピクセル；1 枚 `< 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 ピクセル）は総画素数の条件に不適合です。長さ・フレームレートなど他の条件も満たす必要があります。

画像寸法、ファイルサイズ、エンコードは生成中に検証します。不適合はタスク失敗となり自動返金します。可能な項目は呼び出し前に確認してください。

### 素材の組み合わせルール

* `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]
>
> 次のフィールドは存在するだけで HTTP 400 です。`""`、`[]`、`false`、`null` でも不可のため、フィールド全体を削除してください：`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]
>
> 本編はドラフトのプロンプト、素材、長さ、画角、seed、音声設定を引き継ぎます。`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.