Images

Revision 3 · Updated 2026-11-12 · 5 min read

Generate or edit images through Runtoken.

Choose an operation#

Image generation and image editing use different endpoints and body formats. Choose a model from the catalogue or GET /v1/models, then confirm that it supports the operation you need. Use the platform model ID in requests, not a model-family name.

Generation: POST /v1/images/generations, with a JSON body.
Editing: POST /v1/images/edits, with a multipart body.

Both requests use Authorization: Bearer YOUR_PLATFORM_KEY on https://api.runtoken.net. Replace YOUR_PLATFORM_KEY with a platform API key from the console.

These endpoints do not give every model the same capabilities. Reference-image generation and multipart editing are separate operations; support for one does not establish support for the other.

Currently supported image families#

The current image integrations cover the following families and request types. This list describes platform support, not a promise that every model version from each provider is available. Choose a callable model ID from the platform catalogue.

Family or request type	Supported operation	Request format
OpenAI-compatible image generation	Image generation	JSON through `/v1/images/generations`.
GPT Image	Image generation and editing	JSON generation and multipart editing.
Seedream	Synchronous generation and supported single-image reference or edit inputs	Model-specific JSON.
Ark native image generation	Image generation	Ark-native request structure.
Bailian Qwen 3.0 image	Image generation	Model-specific native request structure.

These labels are not values for the request's model field. Fields for size, quality, multiple outputs, reference images and editing depend on the model version and its platform integration.

OpenAI-compatible image generation#

Use the JSON generation endpoint with a model that accepts the OpenAI-compatible image request format. Billing requires the image-count or token-usage evidence specified by the model's platform pricing rules.

Protocol compatibility does not establish that all OpenAI image parameters or editing operations are supported. The generation example below applies only to models that accept its fields.

GPT Image#

GPT Image supports /v1/images/generations and /v1/images/edits. Use the request fields accepted by the selected GPT Image version.

Requests return synchronously. Streaming, background tasks and partial images are not supported. Token-based billing requires verifiable text and image token details in the response; image count cannot be used to infer those tokens.

Seedream#

Seedream supports synchronous JSON generation and single-image reference or edit inputs recognized by the integration. This does not provide general-purpose multipart editing; do not apply the editing command below to Seedream without confirming the model's input format.

Pixel-tier billing requires a verifiable output-image count and image dimensions. The standard pixel-tier policy requires one returned image. Layer decomposition requires explicit platform pricing support rather than being enabled by default.

Ark native image generation#

This integration uses Ark-native request and response mapping for image generation. Its standard flat pricing policy bills by generated-image count and does not provide general-purpose editing.

Layer billing applies only where the platform has explicitly configured pricing and validated the request. Do not infer layer-generation support from image-generation support alone.

Bailian Qwen 3.0 image#

The current integration supports image generation, with no general-purpose editing support. Native usage evidence must include input/output image counts, dimensions and image tier.

The current billing implementation handles up to 3 input images and 6 output images. These are billing-processing boundaries, not a guarantee that every Qwen model accepts or generates those counts. The selected model's API limits and any input-image allowance must be checked separately against its platform offering.

Generate an image#

The following example uses common OpenAI-compatible image fields to request one image from a text prompt. Use it with a model that accepts these fields; models using a different native JSON structure require their own request body.

Generate from textbash

curl 'https://api.runtoken.net/v1/images/generations' \
  -H 'Authorization: Bearer YOUR_PLATFORM_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "YOUR_MODEL_ID",
    "prompt": "A blue bird",
    "n": 1
  }'

Replace these placeholders before running the example.

Placeholder	Replace with
`YOUR_PLATFORM_KEY`	Your platform API key from the console.
`YOUR_MODEL_ID`	An image-generation model ID.

Use these parameters to describe the image and set the output count.

Parameter	Example value	Description
`prompt`	`A blue bird`	A description of the image to generate.
`n`	`1`	One image in this example; not the maximum output count.

Edit an image#

For a model that supports multipart editing, send the source image as a file field and describe the change in prompt. A generation model with reference-image input does not necessarily support this endpoint.

Edit a local imagebash

curl 'https://api.runtoken.net/v1/images/edits' \
  -H 'Authorization: Bearer YOUR_PLATFORM_KEY' \
  -F 'model=YOUR_MODEL_ID' \
  -F 'image=@YOUR_INPUT_IMAGE.png' \
  -F 'prompt=Add a blue sky'

Replace these placeholders before running the example.

Placeholder	Replace with
`YOUR_PLATFORM_KEY`	Your platform API key from the console.
`YOUR_MODEL_ID`	An image-editing model ID.
`YOUR_INPUT_IMAGE.png`	Path to the local source image.

curl's @ syntax reads the file from disk. -F constructs the multipart body and its content type.

Inputs and results#

Check the selected model's input and output requirements before accepting uploads or displaying results. Native fields are not interchangeable between model families.

Part of the request or response	What to check
Source images	Accepted file formats, file-size limits, dimensions and number of input images.
Generation options	Supported size or aspect ratio, quality, output count and reference-image options.
Response	The native output fields and how image data is represented.
Result handling	How to retrieve or decode the result, and any documented availability period.

The .png filename in the editing example identifies a local file; it is not a complete list of accepted formats. Likewise, n: 1 is an example output count, not a platform-wide default or maximum.

Runtoken does not convert a response into another provider's format. Do not assume every result contains a downloadable URL or that one response parser works for all models.

Current limitations#

The current image integrations return synchronous results. The following capabilities are outside their scope:

Streaming image generation.
Background or asynchronous image tasks.
Partial-image output.
Image generation through tools.

Generation support does not imply editing support. Multiple outputs, reference images and layer decomposition also require explicit model and platform support; do not enable them by copying fields from another provider's example.

Billing#

Image billing uses the synchronous image results and verifiable usage evidence required by the applicable pricing rules. Depending on the model, that evidence can include image count, dimensions, or text and image token details.

The number of generated images is not a substitute for token usage. Missing or inconsistent usage evidence may send a request for billing review.

Use the platform catalogue for sale prices and applicable billing conditions, including pixel tiers, quality options and any input-image allowance. Provider list prices do not establish Runtoken's prices. A zero token rate does not mean the image request is free; the model may be priced on another basis.

Next steps#

For speech and transcription, see Audio. For common routing and billing rules, see the integration guide.

Was this page helpful?