メディアガイド
画像生成
画像の生成や編集、および完了したファイルや非同期タスクの処理
TokenLabは、text-to-image(テキストから画像)、image-to-image(画像から画像)、および画像編集をサポートしています。パラメータはモデルによって異なるため、リクエストを送信する前に選択したモデルのリクエストフィールドを確認してください。
エンドポイントの選択
| 必要な機能 | エンドポイント | 使用するケース | 使用しないケース |
|---|---|---|---|
| Text-to-image | POST /v1/images/generations | ユーザーがテキストのみから開始する場合 | 既存のGPT Imageファイルを編集する場合 |
| Image-to-image | POST /v1/images/generations | モデルが operation: "image-to-image" と画像URLを受け入れる場合 | マルチパートの編集入力を必要とするモデル |
| 画像編集 | POST /v1/images/edits | サポートされている編集モデルで既存の画像を加工する場合 | Nano Banana形式の参照生成 |
| バリエーション | POST /v1/images/variations | 既存のインテグレーションですでにvariations APIを使用している場合 | 新しい参照画像機能 |
| ステータス | GET /v1/tasks/{id} | 作成レスポンスが task_id、status: "pending"、または poll_url を返す場合 | 作成レスポンスにすでに最終的な data[] が含まれている場合 |
必ず model を送信してください。画像APIはデフォルトのモデルを自動選択しません。
モデルの選択
現在の画像モデルは以下で確認できます:
curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
-H "Authorization: Bearer sk-your-api-key"選択したモデルの詳細を開き、以下を確認してください:
- サポートされている操作(
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、および編集フィールドを使用します。このモデルでの生成および編集において、backgroundはautoまたはopaqueを受け入れますが、transparentはサポートされていません。オプションフィールドを省略すると、自動デフォルトが使用されます。- GeminiおよびNano Bananaの画像ファミリーは通常
aspect_ratioを使用します。resolutionはモデル詳細で公開されている場合にのみ送信してください。解像度階層を持つモデルでは、1K、2K、4Kのsizeがresolutionとして送信されます。resolutionと異なる階層を指定すると拒否されます。 - Nano Bananaのimage-to-imageは、
operation: "image-to-image"と参照画像URLを指定して/v1/images/generationsに送信します。 /v1/images/generationsは、トップレベルのimages[]やfile_idを受け入れません。これらは編集フロー用の形式です。- リモート画像参照は、公開されている
httpまたはhttpsURLである必要があります。プライベートネットワークのURL、埋め込み認証情報、URLフラグメント、または処理開始前に期限切れになる可能性のある署名付きURLは送信しないでください。
Text-to-imageの例
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": "A clean product photo of a ceramic coffee cup on a walnut desk",
"size": "1024x1024",
"response_format": "url"
}'参照画像の例
curl https://api.tokenlab.sh/v1/images/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "nano-banana-2",
"operation": "image-to-image",
"prompt": "Keep the product shape, change the background to a bright studio setup",
"image_urls": ["https://example.com/input/product.png"],
"aspect_ratio": "1:1"
}'画像の取得
画像レスポンスは同期または非同期で行われます:
- 同期レスポンスは、
urlまたはb64_jsonを含む最終的なdata[]を返します。 - 非同期レスポンスは、
id、task_id、status、および通常はpoll_urlを返します。パブリックな非同期実行をサポートするモデルで、画像の完了を待たずにタスクを取得するには"async": trueを送信してください。 - 非同期タスクを確認するには、返された
idまたはtask_idを使用してGET /v1/tasks/{id}を呼び出します。 b64_jsonが必要な場合は同期リクエストを使用してください。非同期の画像結果はURLを使用します。
画像結果のURLはTokenLabのメディア結果URLであり、30日間有効です。media_retention.items は各アイテムの保存ステータスと expires_at を報告します。保存ステータスが時間内に不明な場合、レスポンスから media_retention が省略されることがありますが、URLは引き続き機能します。インラインのBase64結果は、このURLコピー保持の対象外です。画像をMedia Libraryに手動で保存すると、個別のライフサイクルが適用されます。データ保持を参照してください。
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer sk-your-api-key"返された画像URL、タスクID、モデル、および独自のユーザー/ジョブIDを永続化してください。終了ステータスになった後はポーリングを継続しないでください。
リリース前チェックリスト
- TokenLabを呼び出す前に、プロンプトの長さ、画像数、URLの到達可能性、ファイルタイプなどのユーザー入力を検証してください。
- 同期的な高解像度リクエストのために、HTTPタイムアウトを十分に長く設定してください。長時間かかる処理には、モデルがサポートしている場合
async: trueを使用してください。 request_id、task_id、poll_url、モデル、エンドポイント、および送信したフィールド名を保存してください。- 画像リクエストがタスクを返す場合、
Idempotency-Keyを使用することで作成リクエストを安全に再試行できます。クライアントのタイムアウト後に同じキーで同じリクエストを送信すると、そのタスクを取得できます。画像を直接返すリクエストの場合、同じキーでの再試行は画像ではなくタスクステータスを返すか、409とidempotent_response_not_replayableを返す可能性があります。キーがない場合は、再試行する前にタスクが作成されたかどうかを確認してください。 - 最終的な課金には、Usageおよび
billing_transaction_idを使用してください。
よくあるエラー
| 症状 | 考えられる原因 | 修正方法 |
|---|---|---|
400 (param: "model") | モデルの指定漏れ | /v1/models?recommended_for=image をクエリし、model を送信する |
| サポートされていないフィールド | そのモデルで文書化されていないフィールド | フィールドを削除するか、そのフィールドを文書化しているモデル/エンドポイントを選択する |
非同期結果に b64_json がない | 非同期画像タスクはURL指向の結果を返す | Base64出力には同期モードを使用する |
| 参照画像が拒否される | エンドポイントの間違い、またはプライベート/期限切れのURL | モデルが文書化している参照形式に合わせ、到達可能なURLを使用する |
APIリファレンス
| トピック | リファレンス |
|---|---|
| 画像の作成 | Create Image |
| 画像の編集 | 画像の編集 |
| 画像バリエーションの作成 | 画像バリエーションの作成 |
| 画像ステータスの取得 | 画像ステータスの取得 |
| タスクステータスの取得 | タスクステータスの取得 |