Image API guide
Use POST /v1/images/generations to generate images from prompts. Models that support reference media can also accept uploaded file_id inputs. The endpoint usually returns results directly rather than using video-style task polling.
Choose a model and parameters
Choose a public model that supports image generation and replace YOUR_MODEL_ID. Keep INONEAPI_API_KEY in your server environment.
| Parameter | Guidance |
|---|---|
model, prompt | Required. Describe subject, composition, style, text, and constraints. |
n | Optional count. Only some models support it (currently the Qwen-Image family, 1–6); unsupported models return one image per request without error. Start with 1 and check the Image count capability on the model detail page. |
size | Optional model-specific size, not a gateway resize instruction. |
quality | Model-specific enum; values are not interchangeable across models. |
output_format, background | Set only when supported. Transparency needs a compatible format such as PNG/WebP. |
response_format | Only providers supporting selection accept url or b64_json; not universally required. |
Start with a minimal request and add verified parameters individually.
Generate from a prompt
Use cURL or server-side Node.js 20+. Do not embed API keys in frontend code.
curl https://api.inoneapi.com/v1/images/generations \
-H "Authorization: Bearer $INONEAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"YOUR_MODEL_ID","prompt":"A clean product photo of a white ceramic cup on a gray background","n":1}'Read and save results
A successful response usually includes created and data[]. Items can contain b64_json or url, optionally revised_prompt. Not every provider returns usage; its absence does not mean free inference.
Base64 encodes raw image bytes without a data URL prefix. The example uses .bin to avoid claiming a PNG/JPEG format before inspecting output_format or actual content. Use the matching extension once verified; renaming does not transcode an image.
URLs are often temporary. Download promptly to your storage. Server-side downloads must not carry your InOneAPI key; validate destination, size, and timeouts. Keep direct links in browsers instead of assuming provider CORS support. Process every returned item and do not assume exactly n images are always present.
{
"created": 1789430400,
"data": [
{
"url": "https://example.com/generated-image.png"
}
]
}Reference images
Upload the image first and use the same API key for generation. This body requires a model that explicitly supports image references:
{
"model": "YOUR_MODEL_ID",
"prompt": "Keep the reference composition and use a white background.",
"input_references": [
{
"type": "image",
"role": "reference",
"source": {
"type": "file",
"file_id": "file_ioa_0123456789abcdef0123456789abcdef"
}
}
]
}input_references is an InOneAPI extension. The gateway validates ownership and image type, retains the role, and hands the model a temporary accessible address. This does not automatically provide arbitrary editing. Roles and counts depend on the model. Files must be ready and still readable. Files are kept for one day and each address is valid for 5 minutes, so asynchronous tasks must fetch the asset inside that window.
Streaming and boundaries
Use stream: true only with models that support streaming, and parse SSE according to the provider. partial_images is model-specific. Partial-image events are not additional final images; an SSE body is not a JSON image array.
Models that require parameter conversion cannot stream and return 400 PROTOCOL_STREAM_UNSUPPORTED. There is no universal image task query, variations endpoint, or automatic async polling. File references do not add an image-edit endpoint. To analyze an image and return text, use a text API with an image-capable model.
Errors and production
For 400, check size, quality, format, reference roles, and capabilities; for 401/403, check key/model access; for 429, honor Retry-After and reduce concurrency; 502 usually means the provider returned a response the platform could not parse. Handle non-success HTTP responses before accessing data[0].
A timeout may occur after upstream completion and billing. Use suitable deadlines and avoid unbounded resubmission. Base64 greatly increases response size and a single response has a size limit, above which the request fails. Bound image count, resolution, and concurrency, and record X-Gateway-Trace-ID.