API ReferenceCompatible Model APIsImages

Image Generations

Generates images from a text prompt using an OpenAI-compatible request. Model and prompt are required. JoyToken forwards supported image options to the selected provider and appends routing and billing details under metadata. This endpoint is non-streaming: do not send stream: true. JoyToken returns one application/json response after generation completes and never emits SSE events or [DONE].

Authentication

AuthorizationBearer

Use Authorization: Bearer $JOY_TOKEN_API_KEY.

Headers

X-Request-IDstringOptional
Optional request identifier for deduplication, billing, logs, and debugging correlation.

Request

This endpoint expects an object.
modelenumRequired

Must be auto. Concrete image model IDs are not accepted.

promptstringRequired>=1 character
Text description of the image to generate.
nintegerOptional>=1
Number of images to generate. Provider limits vary.
qualitystringOptional

Provider-supported image quality, such as standard, hd, medium, or high.

response_formatenumOptional

Output mode. Defaults to b64_json (base64 in data[].b64_json). Set url to receive a hosted image URL in data[].url instead; this only works when every eligible image model supports URL output, otherwise JoyToken falls back to b64_json. Omit unless you specifically need URL output.

sizestringOptional

Provider-supported output dimensions, for example 1024x1024.

stylestringOptional

Provider-supported image style.

userstringOptional

Optional end-user identifier.

backgroundstringOptional

Provider-supported background mode.

moderationstringOptional

Provider-supported moderation setting.

output_compressionintegerOptional0-100
Compression percentage for supported output formats.
output_formatstringOptional

Provider-supported image format, such as png, jpeg, or webp.

Response

Successful non-streaming image generation result returned as one application/json document.

datalist of objects
createdlongOptional
Unix timestamp for the generation result.
metadataobjectOptional

JoyToken routing and billing metadata appended by the gateway when available. In orchestration (multi-task planning) mode this object also carries per-task identifiers, and the response returns one metadata object per task.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error