メディアガイド

画像生成

画像の生成や編集、および完了したファイルや非同期タスクの処理

TokenLabは、text-to-image(テキストから画像)、image-to-image(画像から画像)、および画像編集をサポートしています。パラメータはモデルによって異なるため、リクエストを送信する前に選択したモデルのリクエストフィールドを確認してください。

エンドポイントの選択

必要な機能エンドポイント使用するケース使用しないケース
Text-to-imagePOST /v1/images/generationsユーザーがテキストのみから開始する場合既存のGPT Imageファイルを編集する場合
Image-to-imagePOST /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 または https URLである必要があります。プライベートネットワークの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
画像の編集画像の編集
画像バリエーションの作成画像バリエーションの作成
画像ステータスの取得画像ステータスの取得
タスクステータスの取得タスクステータスの取得

このページの内容