画像生成

POST /v1/images/generations

画像を生成します。既定は同期で、画像ができるまで待ってから応答し、レスポンスの形は OpenAI の images/generations と同じです。OpenAI SDK や中継ゲートウェイからそのまま互換プロバイダーとして使えます。async: true を渡すと非同期になり、送信直後にタスク id が返るので GET /v1/tasks/{id} で結果を取得します。n が 2 以上のときは独立したタスクが n 個作られ、それぞれ個別に課金されます。

パラメータ

パラメータ	型	説明
prompt	string	必須。何を描くか
model	string	/v1/models のモデル id。省略時は既定モデル
n	integer	枚数 1〜4。既定 1
size	string	アスペクト比 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4。既定 1:1。1024x1024 や 1792x1024 のようなピクセル表記も受け付け、最も近い比率に丸めます
quality	string	品質 1k \| 2k \| 4k。既定 1k。spec 指定時はそちらが優先。OpenAI 表記も可：standard / low / auto は 1k、medium / hd / high は 2k
spec	string	モデルの specs[].key から選ぶ仕様キー
reference_images	string[]	参照画像の URL。モデルの max_reference_images を超える分は切り捨て
async	boolean	既定 false で画像を待つ。true なら即座にタスクオブジェクトを返すので /v1/tasks/{id} を自分でポーリング

認識できない値はリクエスト全体を失敗させず、既定値に戻ります（未知の size は 1:1 で描画）。エラーになるのは prompt が空、禁止語に該当、上限に達している、クレジット不足のときだけです。response_format は非対応で、結果は常に URL で返します。

リクエスト例（同期）

bash

curl https://open.pikpikgo.com/v1/images/generations \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "雨のサイバーパンクな夜の街、ネオンの反射",
    "size": "16:9",
    "quality": "2k",
    "n": 1
  }'

レスポンス例（同期）

json

{
  "created": 1786000246,
  "data": [
    { "url": "https://cdn.pikpikgo.com/ai/xxxx.png", "revised_prompt": "雨のサイバーパンクな夜の街、ネオンの反射" }
  ],
  "id": "2608101909450810293847",
  "object": "image.generation",
  "model": "img-std-1",
  "status": "succeeded",
  "n": 1,
  "credits": 10,
  "tasks": [
    {
      "id": "2608101909450810293847",
      "status": "succeeded",
      "data": [{ "url": "https://cdn.pikpikgo.com/ai/xxxx.png", "revised_prompt": "雨のサイバーパンクな夜の街、ネオンの反射" }]
    }
  ]
}

項目	説明
created	レスポンスのタイムスタンプ
data	生成結果。各項目に url と revised_prompt。n>1 では複数入る
id	主タスク id（n>1 のときは最初のサブタスク）
status	succeeded。一部成功もこれになるので、data の件数と n を照らし合わせる
credits	今回差し引かれたクレジットの合計
tasks	すべてのサブタスク。個々の error と結果を含む

同期呼び出しは接続を保持し続けます。1 枚で 30 秒以上かかることが多いので、クライアントのタイムアウトは 300 秒まで延ばしてください。300 秒を超えるとサーバーは 504 generation_timeout を返しますが、タスクは走り続けクレジットも返却されません。メッセージ内のタスク id で /v1/tasks/{id} から後で取得できます。すべて失敗した場合は 502 generation_failed となり、クレジットは自動返却されます。

非同期の使い方

バッチ処理、高並列、レイテンシに敏感な用途向け：送信直後に応答が返り、status は queued、data は空です。

bash

curl https://open.pikpikgo.com/v1/images/generations \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "雨のサイバーパンクな夜の街、ネオンの反射",
    "size": "16:9",
    "quality": "2k",
    "n": 1,
    "async": true
  }'

json

{
  "id": "2608101909450810293847",
  "object": "image.generation",
  "created": 1786000185,
  "model": "img-std-1",
  "status": "queued",
  "n": 1,
  "credits": 10,
  "tasks": [
    { "id": "2608101909450810293847", "status": "queued", "data": [] }
  ],
  "data": []
}

n>1 のときは tasks を走査してください。id だけをポーリングすると残りの画像を取りこぼします。