Image generation

Behavior

Image URLs may expire. Preserve results according to upstream retention rules. Billing may use pictures or tokens depending on rates.

Endpoint and authentication

POST /v1/images/generations

Use an XHub API key: Authorization: Bearer . Do not use upstream provider credentials as gateway keys.

Use the gateway root Base URL shown in the playground, without appending /v1; send requests to the full endpoint path above.

Request example

curl "$XHUB_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $XHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL_NAME","prompt":"A small lighthouse at sunrise.","n":1}'

Request parameters

Field	Type	Description
model	string · required	Public model name; deployment must support this protocol.
prompt	string · required	Image description.
n / size / quality	integer / string	Output count, size and quality; limits depend on upstream.
response_format	string	url or b64_json where supported.

Success response

{
  "created": 1677610602,
  "data": [
    {
      "url": "https://example.com/generated.png"
    }
  ]
}

Field	Type
created	number
data	object[]
data[].url	string

Errors and troubleshooting

HTTP	Meaning
400	Invalid request. Check JSON, parameters and query.
401	Missing or invalid XHub credential.
403	Permission denied. Check model scope or policy.
429	Limit exceeded. Inspect response details and Retry-After.