> 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. # Qwen Image 2.1 > 最大 10 枚の公開 HTTPS 参照画像を使って画像を生成・編集します。1K・2K の出力に対応し、背景が透明な PNG や WebP も指定できます。 `POST https://api.beatapi.io/v1/images/tasks` 最大 10 枚の公開 HTTPS 参照画像を使って画像を生成・編集します。1K・2K の出力に対応し、背景が透明な PNG や WebP も指定できます。 ### 対応する生成モード | モード | 必須の入力 | 入力ルール | | ----------- | --------------------------- | ------------------------------ | | テキストから画像を生成 | `model`, `prompt` | `images` は省略してください。 | | 参照画像を使用 | `model`, `prompt`, `images` | 1～10 個の公開 HTTPS 画像 URL を指定します。 | **リクエストのルール：** auto は最初の参照画像のアスペクト比を引き継ぎ、画像を指定しない場合は 1:1 になります。enhance\_prompt のデフォルト値は画像なしで true、画像ありで false です。透明な背景には png または webp を使用してください。jpeg は使えません。参照画像の例の URL は仮のアドレスです。アクセス可能な HTTPS 画像に置き換えてください。これらは公開 API 仕様に基づく例であり、実行済みのモデル呼び出しではありません。 **非同期処理の流れ：** タスクを作成して `data.id` を保存し、`GET /v1/tasks/{task_id}` で[ステータスをポーリング](/quick-guide#get-task-status)します。`succeeded` の場合は `data.output.media` から結果を取得します。`failed` の場合は `data.error_code` と `data.error_message` を確認し、[エラーと再試行の方針](/quick-guide#errors-and-retry-policy)に従って対処してください。 **ローカルファイルを使う場合：** 先に[入力ファイルをアップロード](/quick-guide#upload-an-input-file)し、返された `data.url` を指定してください。 ## 認証 `Authorization`   `string`   **必須** BeatAPI の API キーを Bearer トークンとして送信します。API キーは[ダッシュボード](https://beatapi.io/dashboard)で作成できます。 ``` Authorization: Bearer ``` 通常の API キーは、信頼できるサーバーで管理してください。リクエストボディには `Content-Type: application/json` が必要です。対応するエンドポイントでは `Idempotency-Key` は任意ですが、同一のリクエストボディで安全に再試行するために指定を推奨します。 ## リクエストボディ `aspect_ratio`   `enum`   **任意** auto は最初の参照画像のアスペクト比を引き継ぎます。画像を指定しない場合は 1:1 になります。 **選択肢:** `auto`, `1:1`, `4:3`, `3:4`, `3:2`, `2:3`, `16:9`, `9:16`, `21:9`, `9:21` \ **デフォルト値:** `"auto"` --- `background`   `enum`   **任意** opaque または transparent を指定します。透明な出力には PNG または WebP が必要です。 **選択肢:** `opaque`, `transparent` \ **デフォルト値:** `"opaque"` --- `enhance_prompt`   `boolean`   **任意** 生成前にプロンプトを書き換えます。デフォルト値は画像なしで true、画像ありで false です。入力にかかわらず適用される一律のデフォルト値はありません。 --- `images`   `string[]`   **任意** 1～10 個の公開 HTTPS 画像 URL です。テキストから画像を生成する場合は省略してください。 **要素数:** 1 – 10 件 --- `model`   `enum`   **必須** qwen-image-2.1 を指定してください。 **選択肢:** `qwen-image-2.1` --- `output_format`   `enum`   **任意** 出力ファイル形式です。透明な背景には png または webp を使用してください。jpeg ではアルファチャンネルを保持できません。 **選択肢:** `png`, `webp`, `jpeg` \ **デフォルト値:** `"png"` --- `prompt`   `string`   **必須** 画像生成または参照画像の編集指示です。1～5000 文字で指定してください。 **文字数:** 1 – 5000 文字 --- `resolution`   `enum`   **任意** 出力の区分を 1K または 2K で指定します。プロンプトで別の区分に変更することはできません。 **選択肢:** `1K`, `2K` \ **デフォルト値:** `"1K"` --- `seed`   `integer`   **任意** 任意の整数で、範囲は 0～2147483647 です。-1 は指定できず、デフォルト値は公開されていません。 **範囲:** 0 – 2147483647 ## リクエスト例 ### テキストから画像を生成 ```bash curl --request POST \ --url https://api.beatapi.io/v1/images/tasks \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "model": "qwen-image-2.1", "prompt": "A white porcelain crane above misty mountains, no text." }' ``` ### 背景が透明な WebP ```bash curl --request POST \ --url https://api.beatapi.io/v1/images/tasks \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "model": "qwen-image-2.1", "prompt": "A single green glass perfume bottle, isolated on a transparent background, no text.", "resolution": "2K", "aspect_ratio": "1:1", "background": "transparent", "output_format": "webp", "enhance_prompt": true, "seed": 0 }' ``` ### 参照画像を使用 ```bash curl --request POST \ --url https://api.beatapi.io/v1/images/tasks \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "model": "qwen-image-2.1", "prompt": "Keep the product shape and label from the reference, place it on a pale stone counter under soft morning light.", "images": [ "https://example.com/product.png" ], "resolution": "1K", "aspect_ratio": "auto", "background": "opaque", "output_format": "png", "enhance_prompt": false, "seed": 42 }' ``` ## レスポンス API 仕様を示す例であり、実行済みタスクや生成結果ではありません。1K の例の金額は同梱の Qwen 料金表に基づきます。実際の使用量はタスクのレスポンスで確認してください。 ```json { "data": { "id": "task_8K2qA", "object": "task", "task_kind": "image", "capability_id": "qwen-image-2.1", "capability_version": null, "media_type": "image", "model": "qwen-image-2.1", "status": "queued", "stage": "queued", "created_at": 1782210000, "updated_at": 1782210000, "completed_at": null, "output": null, "usage": { "credits_reserved": 0.03, "credits_charged": 0.03, "credits_settled": 0, "credits_refunded": 0 }, "request_id": "req_abc123", "error_code": null, "error_message": null } } ``` ## エラー | ステータスコード | 意味と対処方法 | | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | JSON の形式が不正、またはフィールド・値・組み合わせが未対応です（`bad_request`。メッセージにフィールド名が記載されます）。入力がコンテンツ審査で拒否された場合は `content_policy_violation` です。修正せずに再試行しても成功しません。 | | `401` | API キーが未指定（`missing_api_key`）、またはキーが不正・期限切れ・無効・上限到達です（`invalid_api_key`。理由はメッセージに記載されます）。`Authorization: Bearer ` で送信してください。`sk-` 接頭辞の有無にかかわらず使えます。そのまま再試行しないでください。 | | `402` | 残高不足です（`insufficient_credits`）。残高がゼロ、またはこのリクエストの料金に足りません。残高をチャージしてから再度送信してください。それまでは再試行しないでください。 | | `403` | キーまたはアカウントに、この呼び出しの権限がありません（`forbidden`）。例として、無料クレジットでは利用できないモデル（チャージすると利用可能）、キーの IP 許可リスト外からのリクエスト、キーのグループに含まれないモデルがあります。そのまま再試行しないでください。 | | `409` | `Idempotency-Key` が別のリクエストボディで使用済み、または同じキーの最初のリクエストが処理中です（`idempotency_conflict`）。そのまま再試行しないでください。 | | `429` | リクエスト数が上限を超えています（無料モデルの制限を含む `rate_limit_exceeded`）、または同時処理中のタスクが多すぎます（`user_concurrency_exceeded`）。`Retry-After` の秒数だけ待ってから再試行できます。同じ値は `error.retry_after_seconds` にも含まれます。 | | `500` | 予期しない内部エラーです（`internal_error`）。再試行できます。繰り返し発生する場合は、`request_id` を控えてサポートに連絡してください。 | | `503` | リクエストを完了できませんでした（`processing_unavailable`、`processing_timeout`、`processing_failed`、`result_transfer_failed`）。課金されていません。待機時間を段階的に延ばして再試行できます。待機時間が判明している場合は `Retry-After` が返されます。BeatAPI は 502 や 504 を返しません。 |