テキスト → 画像
POST/v1/images
テキストプロンプトから画像を生成します。最大4枚のリファレンス画像で結果を誘導することもできます。
パラメーター
| パラメーター | 説明 |
|---|---|
| prompt必須 string | 画像プロンプト。最大4,000文字(超過分はクレジット消費前に400で拒否)。 |
| model任意 string | 使用する画像モデル。例: nano-banana, gpt-image-2。省略するとデフォルトを使用します。一覧: GET /v1/models?category=image。 |
| aspectRatio任意 string | W:H 形式。例: 1:1, 16:9, 9:16, 21:9。対応する比率はモデルごとに異なります。GET /v1/models?category=imageのsupportedAspectRatiosを参照してください。Nano Banana 系は比率をそのままベンダーへ渡すため、リストにない値はクレジット消費前に400で拒否されます。gpt-image-* は形式が正しければ任意の比率を受け付け、3 つの出力サイズ(1024×1024 / 1024×1536 / 1536×1024)のうち最も近いものに丸めます。 |
| referenceImages任意 string[] | 視覚的なガイドとして使う画像URL、最大4個。ローカルファイルはmultipartのreferenceFilesパートに入れます(各≤20 MB)。リファレンス編集にはnano-bananaを推奨します。 |
| count任意 integer | このリクエストで生成する画像の枚数、1–4(デフォルト 1)。1枚ごとに課金されます。1回で複数枚を参照してください。 |
リクエスト
リクエスト
curl -X POST https://api.picoberry.ai/v1/images \
-H "Authorization: Bearer pb_live_xxx" \
-H "Content-Type: application/json" \
-d '{"prompt":"a low-poly wooden barrel","model":"nano-banana","aspectRatio":"1:1"}'r = requests.post("https://api.picoberry.ai/v1/images", headers=headers,
json={"prompt": "a low-poly wooden barrel", "model": "nano-banana"})
asset_id = r.json()["data"]["id"]const res = await fetch(`${BASE}/v1/images`, {
method: "POST", headers: { ...headers, "Content-Type": "application/json" },
body: JSON.stringify({ prompt: "a low-poly wooden barrel", model: "nano-banana" }),
});
const { id } = (await res.json()).data;レスポンス
レスポンス · 200
{ "success": true, "data": { "id": "019…", "taskStatus": 0, "type": "image" } }taskStatusが2になるまでGET /v1/assets/{id}をポーリングしてください。画像URLはfiles.imageに格納されます。
1回で複数枚
count(1–4)を指定すると、同じプロンプトでその枚数の画像を1回のリクエストで受け取れます。例: nano-banana-2.1 を4枚。トップレベルのフィールドは1枚目のままなので、1枚用に書いたコードもそのまま動きます。assets にすべての画像が順番に入り、同じ batchId を共有します。各 id をポーリングしてください(callbackUrl を指定するとウェブフックも1枚ごとに届きます)。
curl -X POST https://api.picoberry.ai/v1/images \
-H "Authorization: Bearer pb_live_xxx" \
-H "Content-Type: application/json" \
-d '{"prompt":"a low-poly wooden barrel","model":"nano-banana-2.1","count":4}'レスポンス · 200
{ "success": true, "data": {
"id": "019…a0", "taskStatus": 0, "type": "image", "batchId": "019…b0",
"assets": [ { "id": "019…a0", … }, { "id": "019…a1", … }, { "id": "019…a2", … }, { "id": "019…a3", … } ]
} }- クレジット — 1枚ごとに個別に消費されます: 1枚あたりの価格 ×
count(nano-banana-2.11K 4枚 = 240 credits)。この合計がキーの1日の安全上限に計上されます。残高で全枚数をまかなえない場合は何も消費せず、402に合計のrequiredを返します。後で失敗した画像はその1枚だけ返金され、他の画像には影響しません。まれに一部(全部ではない)の画像をキューに登録できなかった場合も呼び出しは成功し、すべての画像がassetsに入ります。登録できなかった画像はすぐに失敗・返金処理され、そのidをポーリングするとtaskStatus: 3です。1枚も登録できなかった場合は呼び出しがエラーを返します。 - 同時実行 — 画像の空き枠が
count枚分必要です(Free 1 · Starter 3 · Pro 6 · Max 15)。そのため Free プランは1リクエスト1枚です。プランの上限を超えるcountは400で拒否されます(再試行しても通りません)。上限内でも実行中のジョブで枠が足りない場合は429(13002)で、枠が空いたら再試行できます。どちらの場合も消費はなく、countが2以上ならエラーの details にrequestedが入ります。 - レート制限 — 毎分120リクエストの制限は枚数ではなくリクエスト数で数えます。
- multipart で送る場合は
countも他の値と同じくフォームフィールドで送ります。
リファレンス画像(ローカルファイル)
ホストされたreferenceImages URLの代わりに、multipart/form-dataで最大4個のreferenceFilesパート(各≤20 MB)を送信できます。残りのフィールドはフォームフィールドになります。
curl -X POST https://api.picoberry.ai/v1/images \
-H "Authorization: Bearer pb_live_xxx" \
-F "prompt=a low-poly wooden barrel" -F "model=nano-banana" \
-F "referenceFiles=@./ref1.png" -F "referenceFiles=@./ref2.png"