Generate images

POST /v1/images/generations

Generates images. Synchronous by default — the call waits until the image is ready and returns the same shape as the OpenAI images/generations endpoint, so the OpenAI SDK and relay gateways work out of the box. Pass async: true to get a task id immediately and read the result from GET /v1/tasks/{id}. With n greater than 1 you get n independent tasks, each billed separately.

Parameters

Parameter	Type	Description
prompt	string	Required. What to draw
model	string	Model id from /v1/models. Defaults to the platform default
n	integer	Number of images, 1–4. Default 1
size	string	Aspect ratio 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4. Default 1:1. Pixel forms such as 1024x1024 or 1792x1024 are accepted too and snapped to the closest ratio
quality	string	Quality tier 1k \| 2k \| 4k. Default 1k, overridden by spec. OpenAI wording is accepted too: standard / low / auto map to 1k, medium / hd / high map to 2k
spec	string	Spec key taken from the model specs[].key
reference_images	string[]	Reference image URLs. Trimmed to the model max_reference_images
async	boolean	Default false — wait for the image. true returns a task object immediately; poll /v1/tasks/{id} yourself

Unrecognised values fall back to defaults instead of failing the request — an unknown size simply renders at 1:1. Only an empty prompt, blocked content, a quota limit or insufficient credits will error out. response_format is not supported; results are always returned as URLs.

Request (synchronous)

bash

curl https://open.pikpikgo.com/v1/images/generations \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a rainy cyberpunk street at night, neon reflections",
    "size": "16:9",
    "quality": "2k",
    "n": 1
  }'

Response (synchronous)

json

{
  "created": 1786000246,
  "data": [
    { "url": "https://cdn.pikpikgo.com/ai/xxxx.png", "revised_prompt": "a rainy cyberpunk street at night, neon reflections" }
  ],
  "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": "a rainy cyberpunk street at night, neon reflections" }]
    }
  ]
}

Field	Description
created	Response timestamp
data	Results, each with url and revised_prompt. Multiple entries when n > 1
id	Primary task id (the first sub-task when n > 1)
status	succeeded — including partial success; compare data length against n yourself
credits	Total credits charged
tasks	All sub-tasks, each with its own error and result

A synchronous call holds the connection open, often for more than 30 seconds per image — raise your client timeout to 300 seconds. Past 300 seconds the server returns 504 generation_timeout; the task keeps running and credits are not refunded, so fetch it later from /v1/tasks/{id} using the id in the message. If every image fails you get 502 generation_failed and the credits are refunded automatically.

Asynchronous flow

Use it for batches, high concurrency or latency-sensitive callers: the call returns immediately with status queued and an empty data array.

bash

curl https://open.pikpikgo.com/v1/images/generations \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a rainy cyberpunk street at night, neon reflections",
    "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": []
}

With n > 1, iterate over tasks. Polling only id silently drops the other images.