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

# 画像生成

> 適切なTokenLab画像エンドポイントを選択し、モデルを意識したリクエストを送信し、同期または非同期の画像結果を安全に処理します。

TokenLabは、テキストから画像、画像から画像、画像編集を公開画像エンドポイントを通じてサポートしています。画像モデルは共通のパラメータセットを共有しないため、プロダクションクライアントはまずエンドポイントを選択し、次にモデルを選択し、そのモデルがサポートするフィールドのみを送信する必要があります。

## 各エンドポイントを使用するタイミング

| ユーザーワークフロー | エンドポイント                       | 使用する場合                                                                                            | 避ける場合                             |
| ---------- | ----------------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------- |
| テキストから画像   | `POST /v1/images/generations` | ユーザーがプロンプトのみから始める場合                                                                               | 公式のGPT画像編集フローが必要な場合               |
| 画像から画像     | `POST /v1/images/generations` | モデルドキュメントが`operation: "image-to-image"`と`image_url`、`image_urls`、または`reference_image_urls`を参照する場合 | モデルがマルチパート編集入力を期待している場合           |
| 画像編集       | `POST /v1/images/edits`       | GPT画像ファミリーモデルなどのサポートされている編集モデルで既存の画像を編集する場合                                                       | Nano Bananaスタイルの画像から画像生成を使用している場合 |
| バリエーション    | `POST /v1/images/variations`  | レガシーのバリエーション互換統合を維持している場合                                                                         | 新しいリファレンス画像ワークフローを構築している場合        |
| ステータス      | `GET /v1/tasks/{id}`          | 作成レスポンスが`task_id`、`status: "pending"`、または`poll_url`を返す場合                                          | 作成レスポンスにすでに最終的な`data[]`が含まれている場合  |

常に`model`を送信してください。画像エンドポイントは、プロダクショントラフィックのために歴史的な暗黙のデフォルトモデルに依存しないように設計されています。

## モデルを選択する

モデルの発見から始め、選択したモデルのTokenLab契約を確認します：

```bash theme={null}
curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"
```

非チャットモデルの場合、リストレスポンスには`tokenlab.public_contract_summary`が含まれることがあります。モデル詳細ページは、より完全な`tokenlab.public_contract`を公開する場合があります。これらのフィールドを使用して確認します：

* サポートされている操作、例えば`text-to-image`、`image-to-image`、または`image-edit`。
* モデルが期待するリクエストエンドポイント。
* リファレンスに使用する形状、例えば`image_url`、`image_urls`、`reference_image_urls`、マルチパート`image`、またはJSON`images[]`。
* モデルが`size`、`aspect_ratio`、`resolution`、`quality`、`background`、`output_format`、または`response_format`を受け入れるかどうか。

## リクエスト形状ルール

* `gpt-image-2`スタイルのリクエストは、OpenAIのような`size`、`quality`、および編集フィールドを使用します。モデルまたはTokenLabが自動デフォルトを使用する場合は、オプションフィールドを省略してください。
* GeminiおよびNano Banana画像ファミリーは通常`aspect_ratio`を使用します。モデル契約がそれを公開している場合にのみ`resolution`を送信してください。
* Nano Banana画像から画像への生成は、`operation: "image-to-image"`とリファレンス画像URLを持つ`/v1/images/generations`に属します。
* `/v1/images/generations`はトップレベルの`images[]`または`file_id`を受け入れません。これらは編集フローの形状です。
* リモート画像リファレンスは、公開の`http`または`https` URLでなければなりません。プライベートネットワークのURL、埋め込まれた資格情報、URLフラグメント、または処理開始前に期限切れになる可能性のある署名付きURLを送信しないでください。

## テキストから画像の例

```bash theme={null}
curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "クリーンな製品写真、ウォルナットデスクの上に置かれたセラミックコーヒーカップ",
    "size": "1024x1024",
    "response_format": "url"
  }'
```

## リファレンス画像の例

```bash theme={null}
curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana",
    "operation": "image-to-image",
    "prompt": "製品の形状を保持し、背景を明るいスタジオセットアップに変更する",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'
```

## 結果の処理

画像レスポンスは同期または非同期です：

* 同期レスポンスは、最終的な`data[]`を`url`または`b64_json`で返します。
* 非同期レスポンスは`id`、`task_id`、`status`、通常は`poll_url`を返します。
* `poll_url`が存在する場合はそれを優先してください。固定のルートが必要な場合は、`GET /v1/tasks/{id}`をポーリングしてください。
* 特に`b64_json`が必要な場合は同期リクエストを使用してください。非同期画像結果はURL指向です。

```bash theme={null}
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"
```

返された画像URL、タスクID、モデル、および自分のユーザー/ジョブIDを保持してください。ターミナルステータスの後はポーリングを続けないでください。

## プロダクションチェックリスト

* TokenLabを呼び出す前にユーザー入力を検証します：プロンプトの長さ、画像の数、URLの到達可能性、およびファイルタイプ。
* 同期の高解像度リクエストのためにHTTPタイムアウトを十分に高く設定します。長時間の作業には利用可能な場合は非同期モードを使用してください。
* サポートのために`request_id`、`task_id`、`poll_url`、モデル、エンドポイント、およびサニタイズされたリクエスト形状を保存します。
* クライアントタイムアウト時には、再試行する前にタスクが作成されたかどうかを確認します。
* 提供者のタスクIDではなく、使用記録および`billing_transaction_id`が存在する場合はそれとコストを照合します。

## 一般的なエラー

| 症状                     | 考えられる原因                       | 修正                                                 |
| ---------------------- | ----------------------------- | -------------------------------------------------- |
| `400`と`param: "model"` | 明示的なモデルが欠落                    | `/v1/models?recommended_for=image`をクエリし、`model`を送信 |
| サポートされていないフィールド        | フィールドがそのモデルの公開契約に含まれていない      | フィールドを削除するか、それを文書化しているモデル/エンドポイントを選択               |
| 非同期結果に`b64_json`がない    | 非同期画像タスクはURL指向の結果を返す          | base64出力のために同期モードを使用                               |
| リファレンス画像が拒否された         | 間違ったエンドポイントまたはプライベート/期限切れのURL | モデルの文書化されたリファレンス形状に一致させ、到達可能なURLを使用                |

## APIリファレンス

| トピック         | リファレンス                                                    |
| ------------ | --------------------------------------------------------- |
| 画像の作成        | [画像の作成](/ja/api-reference/images/create-image)            |
| 画像の編集        | [画像の編集](/ja/api-reference/images/edit-image)              |
| 画像バリエーションの作成 | [画像バリエーションの作成](/ja/api-reference/images/create-variation) |
| 画像のステータス取得   | [画像のステータス取得](/ja/api-reference/images/get-image-status)   |
| タスクのステータス取得  | [タスクのステータス取得](/ja/api-reference/tasks/get-task-status)    |