> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Qwen Image 3.0 画像生成

> qwen-image-3.0 または qwen-image-3.0-pro で画像を生成します

* `qwen-image-3.0` と `qwen-image-3.0-pro` に対応
* テキストからの画像生成、画像編集、複数参照画像に対応
* 参照画像は最大 3 枚
* 1K / 2K と 7 種類のアスペクト比に対応
* 1 リクエストにつき 1 枚のみ生成。`n` は `1` に固定
* 非同期タスクとして実行し、タスク ID で結果を取得

<Warning>
  `image_urls` は公開アクセス可能な画像 URL のみ対応します。base64 Data URI は使用できません。ローカル画像は先に[画像アップロード API](../../uploads/images)でアップロードしてください。
</Warning>

## 対応モデル

| モデル                  | テキストから画像 | 画像から画像 | 参照画像   | 出力    |
| -------------------- | -------- | ------ | ------ | ----- |
| `qwen-image-3.0`     | 対応       | 対応     | 最大 3 枚 | 1 枚固定 |
| `qwen-image-3.0-pro` | 対応       | 対応     | 最大 3 枚 | 1 枚固定 |

## Authorizations

<ParamField header="Authorization" type="string" required>
  すべての API は Bearer Token 認証が必要です。

  [API Key 管理ページ](https://toapis.com/console/token)でキーを取得し、次のヘッダーを送信します。

  ```text theme={null}
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Body

<ParamField body="model" type="string" required>
  モデル名。使用できる値は次の 2 つです。

  * `qwen-image-3.0`
  * `qwen-image-3.0-pro`
</ParamField>

<ParamField body="prompt" type="string" required>
  画像の説明または編集指示。空文字列は指定できません。
</ParamField>

<ParamField body="size" type="string">
  出力画像のアスペクト比：

  `1:1`、`4:3`、`3:4`、`16:9`、`9:16`、`3:2`、`2:3`

  `WIDTH*HEIGHT` または `WIDTHxHEIGHT` のピクセル指定も使用できます。総ピクセル数は `512*512` から `2048*2048`、アスペクト比は `1:8` から `8:1` の範囲にしてください。省略時はモデルがサイズを選択します。
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  `size` にアスペクト比を指定した場合の解像度：

  * `1K` - デフォルト
  * `2K`

  `metadata.resolution` も使用できますが、トップレベルの指定を推奨します。
</ParamField>

<ParamField body="n" type="integer" default={1}>
  生成枚数。`1` に固定されています。`2` 以上を指定すると `400 invalid_request` になります。
</ParamField>

<ParamField body="image_urls" type="string[]">
  画像編集、画像から画像、複数参照に使用する画像 URL の配列です。

  * 最大 3 枚
  * URL のみ対応。base64 は非対応
  * ローカル画像は[画像アップロード API](../../uploads/images)を使用
</ParamField>

<ParamField body="client_business_id" type="string">
  注文 ID など、クライアント側の業務 ID。指定すると同じステータス API でこの ID を使って照会できます。
</ParamField>

<ParamField body="metadata" type="object">
  Qwen Image の高度なパラメータです。

  <Expandable title="metadata のプロパティ">
    <ParamField body="metadata.prompt_extend" type="boolean" default={true}>
      プロンプトを自動的に最適化・拡張するかどうか。
    </ParamField>

    <ParamField body="metadata.prompt_extend_mode" type="string">
      拡張モード。`direct`、またはテキストから画像の場合のみ `agent`。`image_urls` がある場合、`agent` は自動的に `direct` になります。
    </ParamField>

    <ParamField body="metadata.negative_prompt" type="string">
      生成したくない内容を指定するネガティブプロンプト。
    </ParamField>

    <ParamField body="metadata.seed" type="integer">
      乱数シード。同じ結果を保証するものではありませんが、近い結果の生成に役立ちます。
    </ParamField>

    <ParamField body="metadata.watermark" type="boolean" default={false}>
      ウォーターマークを追加するかどうか。
    </ParamField>
  </Expandable>
</ParamField>

## 解像度とピクセルサイズ

アスペクト比を指定した場合、両モデルで次のピクセルサイズに変換されます。

| 比率     | 1K        | 2K        |
| ------ | --------- | --------- |
| `1:1`  | 1024×1024 | 2048×2048 |
| `4:3`  | 1152×864  | 1600×1200 |
| `3:4`  | 864×1152  | 1200×1600 |
| `16:9` | 1280×720  | 1920×1080 |
| `9:16` | 720×1280  | 1080×1920 |
| `3:2`  | 1152×768  | 1728×1152 |
| `2:3`  | 768×1152  | 1152×1728 |

## Response

<ResponseField name="id" type="string">ステータス照会に使用するタスク ID。</ResponseField>
<ResponseField name="object" type="string">常に `generation.task`。</ResponseField>
<ResponseField name="model" type="string">使用したモデル。</ResponseField>
<ResponseField name="status" type="string">`queued`、`in_progress`、`completed`、`failed`。</ResponseField>
<ResponseField name="progress" type="integer">0 から 100 の進捗率。</ResponseField>
<ResponseField name="created_at" type="integer">Unix タイムスタンプの作成時刻。</ResponseField>

## リクエスト例

<RequestExample>
  ```bash cURL（テキストから画像） theme={null}
  curl --request POST \
    --url https://toapis.com/v1/images/generations \
    --header 'Authorization: Bearer <YOUR_API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "qwen-image-3.0",
      "prompt": "雲海の上にある古都、金色の朝日、映画ポスターの構図、読みやすい日本語タイトル",
      "size": "16:9",
      "resolution": "2K",
      "n": 1,
      "metadata": {
        "prompt_extend": true,
        "negative_prompt": "ぼやけ、低品質、文字化け",
        "watermark": false
      }
    }'
  ```

  ```bash cURL（複数参照画像） theme={null}
  curl --request POST \
    --url https://toapis.com/v1/images/generations \
    --header 'Authorization: Bearer <YOUR_API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "qwen-image-3.0-pro",
      "prompt": "1 枚目の人物と 2 枚目の衣装を維持し、現代的な雑誌表紙にしてください",
      "image_urls": [
        "https://example.com/person.png",
        "https://example.com/outfit.png"
      ],
      "size": "3:4",
      "resolution": "2K",
      "n": 1
    }'
  ```
</RequestExample>

## タスクの送信結果

```json theme={null}
{
  "id": "task_img_abc123def456",
  "object": "generation.task",
  "model": "qwen-image-3.0-pro",
  "status": "queued",
  "progress": 0,
  "created_at": 1787270400
}
```

## タスクの照会

```bash theme={null}
curl --request GET \
  --url https://toapis.com/v1/images/generations/task_img_abc123def456 \
  --header 'Authorization: Bearer <YOUR_API_KEY>'
```

レスポンスの詳細とポーリング方法は[画像タスクのステータス取得](../../tasks/image-status)を参照してください。

```json theme={null}
{
  "id": "task_img_abc123def456",
  "object": "generation.task",
  "model": "qwen-image-3.0-pro",
  "status": "completed",
  "progress": 100,
  "result": {
    "type": "image",
    "data": [
      { "url": "https://files.toapis.com/generated/qwen-image-result.png" }
    ]
  }
}
```

<Warning>生成画像の URL は 24 時間有効です。`expires_at` より前に保存してください。</Warning>

## 料金

* 成功した出力：1 リクエスト `$0.03`
* 参照画像：1 枚 `$0.003`
* 参照画像の無料枠はありません
* 2 つのモデルは現在同じ料金ルールです