Image API guide
Use POST /v1/images/generations to generate images from prompts. Models and mappings supporting 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 with an image API mapping 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. Start with 1; some models only generate one image. |
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 mapping 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, replaces the source with a COS signed URL, retains the role, then applies the mapping. This does not automatically provide arbitrary editing. Roles and counts depend on the model. Files must be ready and still exist. Retention uses a one-day lifecycle; signed URLs last 5 minutes, so asynchronous reads must happen while both remain available.
Streaming and boundaries
Use stream: true only with native streaming support 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.
Requests requiring request DSL conversion cannot stream through that conversion. 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 may indicate upstream or normalization failure. 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 increases body size and memory use; the default DSL response buffer is 32 MiB. Bound image count, resolution, and concurrency, and record X-Gateway-Trace-ID.