Image generation

For file inputs, upload through the Files API, then reference the returned file_id. The gateway converts the input; provider acceptance is determined upstream.

Reference assets with input_references: [{"type":"image","role":"reference","source":{"type":"file","file_id":"..."}}]. Type must match the image/audio/video file. The gateway replaces source with a COS signed URL, preserves role, then applies DSL. Existing required fields remain required. For Images and Speech, input_references is an InOneAPI extension.

The public contract follows OpenAI Images: POST /v1/images/generations. Native providers pass through; administrators map non-native JSON with DSL. InOneAPI requires an explicit public model ID instead of relying on OpenAI model defaults.

Minimal request

Replace YOUR_MODEL_ID with the exact model detail ID; do not add a provider prefix. Optional parameters and voices depend on the selected model. App attribution headers are commented out.

# -H "X-APP-NAME: Your App Name"
# -H "X-APP-URL: https://your-app.example.com"
curl "https://api.inoneapi.com/v1/images/generations" \
  -H "Authorization: Bearer $INONEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "YOUR_MODEL_ID",
  "prompt": "A blue bird on a white background"
}'

Complete generation parameter reference

Parameter	Type	Complete generation parameter reference
`model`	string	Required public model ID, replaced by the selected upstream model ID.
`prompt`	string	Required prompt describing subject, composition, style, text and constraints. Model-specific length limits apply.
`n`	integer	Optional image count, commonly 1–10; some models allow only 1. Omitted defaults are upstream-defined.
`size`	string	Optional WIDTHxHEIGHT or auto. Common values: 1024x1024, 1536x1024, 1024x1536. Model-specific constraints apply; no gateway resizing.
`quality`	string	Optional auto/low/medium/high for GPT Image-style models, or standard/hd for some legacy models; not universally interchangeable.
`style`	string	Optional vivid/natural, only for models supporting this legacy style parameter.
`response_format`	string	Optional url/b64_json when supported. Native GPT Image always returns Base64 and does not accept response_format; omit it.
`background`	string	Optional auto/opaque/transparent. Transparency requires supporting models and png/webp, not jpeg.
`output_format`	string	Optional png/jpeg/webp, only when supported. Provider defaults apply when omitted.
`output_compression`	integer	Optional integer 0–100, only for jpeg/webp compression, not png.
`moderation`	string	Optional auto/low when supported; this does not bypass provider safety controls.
`user`	string	Optional end-user identifier. Avoid email addresses, phone numbers and sensitive identifiers.
`stream`	boolean	Optional boolean; non-streaming by default. Streaming passes through native providers only; request DSL cannot transform streaming requests.
`partial_images`	integer	Optional integer 0–3 for streaming partial images. Not the total image count; the final image may arrive sooner.

Complete examples by model capability

No single all-parameter request is valid for every model. Examples separate GPT Image-style output from legacy style/URL parameters. Replace placeholder model IDs with enabled models. The streaming example covers partial_images.

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 blue bird on a white background",
  "n": 1,
  "size": "1024x1024",
  "quality": "high",
  "background": "opaque",
  "output_format": "jpeg",
  "output_compression": 90,
  "moderation": "auto",
  "user": "user_123",
  "stream": false
}'

{"model":"YOUR_MODEL_ID","prompt":"A blue bird","n":1,"size":"1024x1024","quality":"hd","style":"vivid","response_format":"url","user":"user_123"}

curl -N 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 blue bird","stream":true,"partial_images":2}'

Response fields and saving output

{
  "created":1788580800,
  "data":[{"b64_json":"REPLACE_WITH_IMAGE_BYTES"}],
  "background":"opaque",
  "output_format":"jpeg",
  "size":"1024x1024",
  "quality":"high",
  "usage":{"input_tokens":100,"output_tokens":1000,"total_tokens":1100,"input_tokens_details":{"text_tokens":60,"image_tokens":40}}
}

Field	Response fields and saving output
`created`	Integer Unix seconds, unlike ISO timestamps in the video contract.
`data[]`	Ordered result array. Usually corresponds to n; do not assume failed requests contain every result.
`data[].b64_json`	Base64 image bytes without a data URL prefix. Decode using the returned output format.
`data[].url`	Temporary download URL only when supported. Download promptly; permanent hosting is not guaranteed.
`data[].revised_prompt`	Optional provider-revised prompt, not necessarily the original prompt.
`background / output_format / size / quality`	Optional actual background, format, dimensions and quality metadata.
`usage`	Optional token usage; some providers omit it. Missing usage does not mean a free request.
`usage.input_tokens / output_tokens / total_tokens`	Optional input, output and total tokens. input_tokens_details.text_tokens/image_tokens split input usage. Metering and pricing are configured separately.

Errors, streaming and boundaries

400 may indicate invalid parameters, media or DSL input; check credentials for 401/403; back off using Retry-After for 429. 502 may indicate failed normalization or a DSL response buffer overflow. Record X-Gateway-Trace-ID, not credentials or private images. Generation timeouts can have ambiguous outcomes: do not blindly retry. This is synchronous output or native SSE, not a video-style task API. Generic image task retrieval, asynchronous polling conversion and variations are not implemented. DSL does not transform SSE events. Large Base64 responses are bounded by GATEWAY_RESPONSE_BUFFER_BYTES (32 MiB by default); size it against concurrency and memory.

Administrator and AI mapping guide

Configure image_path. Use {"version":1} for native passthrough. Generation uses request/response. Native protocol is enabled by default; disable it to edit and test the DSL. Use mode=replace for strict provider schemas. See repository docs/image-protocol-dsl.md and docs/protocol-mapping-dsl.schema.json for complete fixtures, field mappings, enums and capability-gap checks. Protocol DSL does not set prices; metering reads raw upstream responses.

Try in the playground

The console Playground and the model detail “Try now” panel call this endpoint according to the model’s output modalities. They display and save data[].url and data[].b64_json results. Select the output type when a model supports both text and images. Catalog modality tabs match output capabilities only.