画像

画像を作るエンドポイントは 2 つあります。

• POST /v1/images/generations は、テキストのプロンプトから画像を生成します。
• POST /v1/images/edits は、1 枚以上の参照画像を、テキストのプロンプトで編集します。

どちらのエンドポイントも、Authorization: Bearer で送る API キーが必要です。認証を参照してください。本文は JSON です。multipart のアップロードには対応していないため、参照画像は、JSON の中に URL または data URI として入れて送ります。

すべての画像のリクエストは、ジョブとして実行されます。リクエストは、ジョブの完了を待ってレスポンスで画像を返すことも、ジョブをすぐに返して、結果を後で受け取れるようにすることもできます。

モデルとプロンプトを送ります。例では、sakuranbo/cherryimage-1.0-pro を使います。

curl -X POST "https://api.sakuranbo.ai/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SAKURANBO_API_KEY" \
  -d '{
  "model": "sakuranbo/cherryimage-1.0-pro",
  "prompt": "A matte ceramic coffee mug on a walnut desk, soft morning light, shallow depth of field",
  "resolution": "2k",
  "aspect_ratio": "4:3"
}'

const response = await fetch("https://api.sakuranbo.ai/v1/images/generations", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.SAKURANBO_API_KEY}`,
  },
  body: JSON.stringify({
    "model": "sakuranbo/cherryimage-1.0-pro",
    "prompt": "A matte ceramic coffee mug on a walnut desk, soft morning light, shallow depth of field",
    "resolution": "2k",
    "aspect_ratio": "4:3"
  }),
});
const data = await response.json();
console.log(data);

import os

import requests

response = requests.post(
    "https://api.sakuranbo.ai/v1/images/generations",
    headers={
        "Authorization": f"Bearer {os.environ['SAKURANBO_API_KEY']}",
    },
    json={
        "model": "sakuranbo/cherryimage-1.0-pro",
        "prompt": "A matte ceramic coffee mug on a walnut desk, soft morning light, shallow depth of field",
        "resolution": "2k",
        "aspect_ratio": "4:3",
    },
)
print(response.json())

例のモデルの入力パラメータは次のとおりです。

リクエスト本文には、次のフィールドがあります。

resolution で価格が決まります。表にないパラメータや、範囲外の値を指定すると、400 と invalid_request を返します。error.param にパラメータの名前が入り、error.details.allowed、error.details.minimum、error.details.maximum に有効な値が入ります。

既定では、リクエストは画像ができるまで待ちます。

• ジョブが最大の待ち時間内に終わると、レスポンスは画像を含む 200 です。待ち時間は、API リファレンスに載っています。
• その時間を過ぎてもジョブが実行中のときは、レスポンスは、ジョブと、ジョブを指す Location ヘッダを持つ 202 です。生成は続きます。
• Prefer: respond-async を送ると、レスポンスはすぐに 202 になり、Preference-Applied: respond-async ヘッダが付きます。

curl -X POST "https://api.sakuranbo.ai/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SAKURANBO_API_KEY" \
  -H "Prefer: respond-async" \
  -d '{
  "model": "sakuranbo/cherryimage-1.0-pro",
  "prompt": "A matte ceramic coffee mug on a walnut desk, soft morning light, shallow depth of field",
  "resolution": "2k",
  "aspect_ratio": "4:3"
}'

const response = await fetch("https://api.sakuranbo.ai/v1/images/generations", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.SAKURANBO_API_KEY}`,
    Prefer: "respond-async",
  },
  body: JSON.stringify({
    "model": "sakuranbo/cherryimage-1.0-pro",
    "prompt": "A matte ceramic coffee mug on a walnut desk, soft morning light, shallow depth of field",
    "resolution": "2k",
    "aspect_ratio": "4:3"
  }),
});
const data = await response.json();
console.log(data);

import os

import requests

response = requests.post(
    "https://api.sakuranbo.ai/v1/images/generations",
    headers={
        "Authorization": f"Bearer {os.environ['SAKURANBO_API_KEY']}",
        "Prefer": "respond-async",
    },
    json={
        "model": "sakuranbo/cherryimage-1.0-pro",
        "prompt": "A matte ceramic coffee mug on a walnut desk, soft morning light, shallow depth of field",
        "resolution": "2k",
        "aspect_ratio": "4:3",
    },
)
print(response.json())

202 のレスポンスのあとは、2 通りのどちらかで結果を受け取ります。ジョブの説明に従ってジョブをポーリングするか、Webhookの説明に従って job.succeeded、job.failed、job.cancelled のイベントを受け取ります。

リクエストが待っている間にジョブが失敗すると、レスポンスは 202 ではなくエラーになり、error.details.job_id にジョブの ID が入ります。202 のレスポンスのあとの失敗は、代わりにジョブの error フィールドに現れ、ジョブを読み取るリクエストは 200 を返します。

200 のレスポンスには、次のフィールドがあります。

cost は最終的な請求額です。同じ金額が X-Usage-Cost-Usd ヘッダにも入ります。job_id は、画像を作ったジョブの ID です。

response_format で、画像の返し方を選びます。

• url が既定です。data の各項目に、url と expires_at が入ります。URL は署名付きです。API キーは不要で、expires_at まで使えます。expires_at は、ジョブが完了してから 7 日後です。それまでは、URL を知っていれば誰でも画像をダウンロードできるため、URL は秘密として扱ってください。expires_at を過ぎるとファイルは削除されるため、必要な画像は保存してください。
• b64_json は、画像を base64 でレスポンス本文に入れます。画像が大きすぎて本文に入れきれないときは、入らない画像が url の項目として返ります。

data には、届けた画像 1 枚につき 1 項目が入ります。まとめて生成した画像の一部が失敗したときは、data の項目が n より少なくなることがあり、課金されるのは届いた画像の分だけです。

POST /v1/images/edits は、生成のエンドポイントと同じフィールドを受け取り、images フィールドが必須です。

curl -X POST "https://api.sakuranbo.ai/v1/images/edits" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SAKURANBO_API_KEY" \
  -d '{
  "model": "sakuranbo/cherryimage-1.0-pro",
  "prompt": "Make the mug dark blue",
  "images": [
    "https://example.com/reference.png"
  ]
}'

const response = await fetch("https://api.sakuranbo.ai/v1/images/edits", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.SAKURANBO_API_KEY}`,
  },
  body: JSON.stringify({
    "model": "sakuranbo/cherryimage-1.0-pro",
    "prompt": "Make the mug dark blue",
    "images": [
      "https://example.com/reference.png"
    ]
  }),
});
const data = await response.json();
console.log(data);

import os

import requests

response = requests.post(
    "https://api.sakuranbo.ai/v1/images/edits",
    headers={
        "Authorization": f"Bearer {os.environ['SAKURANBO_API_KEY']}",
    },
    json={
        "model": "sakuranbo/cherryimage-1.0-pro",
        "prompt": "Make the mug dark blue",
        "images": [
            "https://example.com/reference.png",
        ],
    },
)
print(response.json())

images は参照画像のリストです。各項目は、公開された https の URL か、data:image/...;base64, の URI です。画像の形式は PNG、JPEG、WebP、GIF です。プロンプトで 1 枚目や 2 枚目の画像を指せるため、順番が意味を持ちます。data URI のサイズ上限は URL より小さいので、大きな画像は公開された URL で送ってください。

サーバーは、ジョブを作る前に、各 URL を取得して確認します。リダイレクトには従わず、認証情報、IP アドレス、内部向けのホスト名を含む URL は拒否します。使えない画像を指定すると、400 と invalid_request を返します。error.param は、images に項目のインデックスを続けたものです。URL では、error.details.reason に問題の内容が入ります。大きすぎる data URI では、error.details.max_bytes に上限が入ります。

レスポンスは、生成と同じです。

自分で決めた値の Idempotency-Key ヘッダを送ります。同じキーと同じ内容のリクエストが再び届くと、同じジョブが返り、課金は 1 回だけです。同じキーで内容の違うリクエストを送ると、409 と idempotency_conflict を返します。キーは一定の期間だけ記憶され、その期間は API リファレンスに載っています。

リクエストが受理されると、Sakuranbo AI は、依頼した画像の価格を残高から確保します。ジョブが終わると、届けた画像の分の請求額を計算し、確保した金額の残りを残高に戻します。キャンセルされたジョブ、時間切れになったジョブ、拒否されたジョブは課金されません。失敗したジョブも、通常は課金されず、確保した金額は残高に戻ります。

まれに、リクエストがモデルの提供元に届いたかどうかを、Sakuranbo AI が確認できないことがあります。その場合、ジョブは upstream_error で失敗し、確保した金額は、課金されるかどうかを Sakuranbo AI が確認するまで確保されたままになります。確保されたままのときは、ジョブ ID を添えてサポートにお問い合わせください。

価格は、モデル、resolution、画像の枚数で決まります。モデルカタログと料金のページを参照するか、実行する前に POST /v1/estimate で計算してください。見積 APIを参照してください。

モデルの提供元が、プロンプト、参照画像、または生成された画像を、その内容を理由に拒否することがあります。その場合、ジョブは content_policy_violation で失敗し、課金されません。ジョブを待っているリクエストには、このコードと 422 を返し、error.details.job_id がジョブの ID です。202 のレスポンスを返したあとは、ジョブの error フィールドにこのコードが入ります。

POST /v1/images/edits も、同じコードを返します。429 または 503 のレスポンスでは、Retry-After ヘッダの秒数だけ待ってから再試行してください。402 のレスポンスには error.details.limit_source が入り、値は balance か key です。残高とキーの利用上限を参照してください。すべてのコードは、エラーを参照してください。