画像生成

​

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

​

モデルを選択する

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、またはJSONimages[]。
• モデルがsize、aspect_ratio、resolution、quality、background、output_format、またはresponse_formatを受け入れるかどうか。

​

リクエスト形状ルール

• 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を送信しないでください。

​

テキストから画像の例

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

​

リファレンス画像の例

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指向です。

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

​

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

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

​

一般的なエラー

​

APIリファレンス