> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.beatapi.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server. # BeatAPI Image API > 画像生成モデルの参照画像の上限、解像度、アスペクト比、モデル別のリクエスト仕様を比較します。 # Image API 安定した BeatAPI モデル ID で、非同期の画像生成タスクを作成します。 | モデル | 入力モード | 必須項目 | 主な設定 | | ------------------------------------------------------------- | --------- | ---------------- | ---------------------------------------------------- | | [`qwen-image-2.1`](/image-api/qwen-image-2-1) | テキスト、参照画像 | `model`、`prompt` | 参照最大 10 枚、1K/2K、透過 PNG/WebP、条件付きプロンプト補強 | | [`nano-banana`](/image-api/nano-banana) | テキスト、参照画像 | `model`、`prompt` | 参照最大 10 枚、アスペクト比、PNG/JPEG 出力 | | [`nano-banana-2`](/image-api/nano-banana-2) | テキスト、参照画像 | `model`、`prompt` | 参照最大 10 枚、1K/2K/4K、PNG/JPEG 出力 | | [`nano-banana-2.1`](/image-api/nano-banana-2-1) | テキスト、参照画像 | `model`、`prompt` | Nano Banana 2 の後継。参照最大 14 枚、1K/2K/4K、PNG/JPEG 出力 | | [`nano-banana-2-lite`](/image-api/nano-banana-2-lite) | テキスト、参照画像 | `model`、`prompt` | 参照最大 14 枚、固定 1K、PNG/JPEG 出力 | | [`nano-banana-pro`](/image-api/nano-banana-pro) | テキスト、参照画像 | `model`、`prompt` | 参照最大 8 枚、最大 4K | | [`gpt-image-2`](/image-api/gpt-image-2) | テキスト、参照画像 | `model`、`prompt` | 参照最大 16 枚、幅広いアスペクト比、最大 4K | | [`gpt-image-2.5-flare`](/image-api/gpt-image-2-5-flare) | テキスト、参照画像 | `model`、`prompt` | 2.5 の 2 モデルのうち、高速な標準モデル。参照最大 16 枚、16 種類のアスペクト比、最大 4K | | [`gpt-image-2.5-sunburst`](/image-api/gpt-image-2-5-sunburst) | テキスト、参照画像 | `model`、`prompt` | 2.5 の 2 モデルのうち、精度重視のモデル。参照最大 16 枚、16 種類のアスペクト比、最大 4K | | [`seedream-5-pro`](/image-api/seedream-5-pro) | テキスト、参照画像 | `model`、`prompt` | 参照最大 10 枚、1K/2K/4K | | [`grok-imagine-image-2.0`](/image-api/grok-imagine-image-2-0) | テキスト、参照画像 | `model`、`prompt` | 参照最大 5 枚、編集モードの自動選択 | 各フィールド、初期値、列挙値、組み合わせのルール、リクエスト例、レスポンス、エラーの詳細は、対応するモデルページを参照してください。 ## 利用可能なモデルを取得する `GET /v1/media/models` | パラメーター | 場所 | 型 | 必須 | 許容値 | | ------------ | --- | ------ | --- | --------------- | | `media_type` | クエリ | string | いいえ | `image`、`video` | この公開エンドポイントは認証不要です。 ```bash curl "https://api.beatapi.io/v1/media/models?media_type=image" ``` ```json { "data": { "object": "list", "data": [ { "id": "gpt-image-2", "object": "generation_model", "name": "GPT Image 2", "media_type": "image", "input_modes": ["text", "image"] }, { "id": "gpt-image-2.5-flare", "object": "generation_model", "name": "GPT Image 2.5 Flare", "media_type": "image", "input_modes": ["text", "image"] }, { "id": "gpt-image-2.5-sunburst", "object": "generation_model", "name": "GPT Image 2.5 Sunburst", "media_type": "image", "input_modes": ["text", "image"] } ] } } ``` | フィールド | 型 | 意味 | | ------------- | --------- | ----------------------------------------- | | `id` | string | 安定した公開モデルエイリアス | | `object` | string | `generation_model` | | `name` | string | 表示名 | | `media_type` | string | `image` または `video` | | `input_modes` | string\[] | `text`、`image`、`frames`、`reference` のいずれか | 内部のモデル接続経路は公開仕様に含まれません。 ## 共通の作成仕様 `POST /v1/images/tasks` | ヘッダー | 型 | 必須 | ルール | | ----------------- | ------ | ------ | -------------------------- | | `Authorization` | string | はい | `Bearer ` | | `Content-Type` | string | はい | `application/json` | | `Idempotency-Key` | string | いいえ、推奨 | 最大 255 文字。論理的な作成操作ごとに 1 つ | 本文は、いずれか 1 つのモデルスキーマに正確に一致する必要があります。`model` がスキーマの判別項目で、不明なフィールドは拒否されます。 ```bash curl https://api.beatapi.io/v1/images/tasks \ -X POST \ -H "Authorization: Bearer $BEATAPI_API_KEY" \ -H "Idempotency-Key: image-gpt-image-2-001" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "prompt": "Editorial product photograph on a warm stone pedestal.", "aspect_ratio": "1:1", "resolution": "1K" }' ``` 有効なリクエストには `201 Created` が返り、`data.id`、`task_kind="image"`、選択した `model`、`status="queued"`、利用量、`request_id` が含まれます。`GET /v1/tasks/{task_id}` を 5–10 秒ごとに確認し、`succeeded` または `failed` で終了します。成功した画像は `data.output.media[]` と `data.output.r2_url` に入ります。 同じ冪等キーと完全に同じ本文で再送すると、受け付け済みのタスクを返します。同じキーを異なる本文で使うと `409 idempotency_conflict` を返します。 ## 共通のエラー | HTTP | 共通コード | クライアントの対処 | | ----- | ------------------------------------------------------------------------------------------------ | ------------------------------------- | | `400` | `bad_request` | フィールド、値、組み合わせ、件数、メディア URL を修正 | | `400` | `content_policy_violation` | プロンプトや入力を変更。変更せず再送しない | | `401` | `missing_api_key` / `invalid_api_key` | Bearer キーを送信、または不正、期限切れ、無効、上限到達のキーを交換 | | `402` | `insufficient_credits` | 新しいタスクを作る前にチャージ | | `403` | `forbidden` | キーまたはアカウントで許可されていない。無料クレジット対象外のモデルなど | | `409` | `idempotency_conflict` | 完全に同じ本文の場合にのみキーを再利用 | | `429` | `rate_limit_exceeded` / `user_concurrency_exceeded` | `Retry-After` に従うか、処理中のタスクの完了を待つ | | `500` | `internal_error` | バックオフして 1 回再試行 | | `503` | `processing_unavailable` / `processing_timeout` / `processing_failed` / `result_transfer_failed` | バックオフして再試行。課金なし | エラーレスポンスは `error.code`、英語の `error.message`、`error.retryable`、`error.request_id` を含み、`429` には `error.retry_after_seconds` も含まれます。受け付け後に失敗したタスクの取得自体は `200` です。`data.error_code` と[エラー](/errors)で、全コードと再試行ルールを確認してください。各モデルページには本番のリクエスト仕様を掲載しています。