Image Generation (Create)

Reference for POST /v1/images/generations, including prompts, sizes, reference images, async task creation, credits, and callbacks.

This endpoint is implemented by the UnderSky Rust gateway. Availability depends on the configured upstream provider and media storage.

Submit an asynchronous image generation request. The response returns a task ID that you can poll for status using the Image Generation (Status) endpoint.

Endpoint

POST https://api.undersky.ai/v1/images/generations

Parameters

Parameter	Type	Required	Description
prompt	string	Yes	Text description of the image to generate
model	string	Yes	Model ID from the supported models table below
referenceImages	string \| string[]	No	URL(s) of reference images for style or content guidance
number	number	No	Number of images to generate, 1-4. Default: `1`
size	string	No	Image dimensions (e.g. `"1024x1024"`) or aspect ratio (e.g. `"9:16"`, model-dependent)
callbackUrl	string	No	Webhook URL to receive a POST when generation completes

Supported Models

Model ID	Name	Price
`gpt-4o-image`	GPT-4o Image	0.5 credits/image
`gpt-image-2`	GPT Image 2	0.01 credits/image
`gemini-3.1-flash-image-preview`	Gemini 3.1 Flash Image Preview	approximately 0.081714 credits/image

Request

curl -X POST https://api.undersky.ai/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-image",
    "prompt": "A cat astronaut floating in space, digital art",
    "number": 1,
    "size": "1024x1024"
  }'

Response

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Notes

Task creation reserves model price × number; completion settles the actual number of generated images.
Failed tasks release the reservation; partial tasks charge only for successful images.
If your balance is insufficient, the API returns 402 Payment Required.
Use the returned id to poll for results via the Status endpoint.