画像生成

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

各エンドポイントを使用するタイミングCopy Anchor Link

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

モデルを選択するCopy Anchor Link

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

curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"

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

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

リクエスト形状ルールCopy Anchor Link

• gpt-image-2スタイルのリクエストは、OpenAIのようなsize、quality、および編集フィールドを使用します。生成と編集の background は auto または opaque を受け付けますが、transparent はサポートされません。モデルまたは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を送信しないでください。

テキストから画像の例Copy Anchor Link

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"
  }'

リファレンス画像の例Copy Anchor Link

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": "製品の形状を保持し、背景を明るいスタジオセットアップに変更する",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

結果の処理Copy Anchor Link

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

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

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

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

プロダクションチェックリストCopy Anchor Link

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

一般的なエラーCopy Anchor Link

APIリファレンスCopy Anchor Link