生成

テキスト → 画像

POST/v1/images

テキストプロンプトから画像を生成します。最大4枚のリファレンス画像で結果を誘導することもできます。

非同期 idを返します。ポーリングまたはウェブフック一般的 ~10–40sコスト 1枚あたり ≈15–200 credits

パラメーター

パラメーター説明
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", … } ]
} }

リファレンス画像(ローカルファイル)

ホストされた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"