Image Models
Generate and edit images through the OneMux image model API.
API Overview
Image models use a dedicated Images API. Do not send image generation requests to /v1/chat/completions.
- Image generation:
POST https://api.onemux.net/v1/images/generations - Image editing:
POST https://api.onemux.net/v1/images/edits - Authentication:
Authorization: Bearer YOUR_API_KEY - Models: Use the actual image model ID returned by the current model list endpoint
First, retrieve the currently available models:
curl https://api.onemux.net/v1/models \
-H "Authorization: Bearer $ONEMUX_API_KEY"
Whether an image model supports generation, editing, reference images, sizes, quality, output formats, and other parameters depends on the model list and the actual capabilities of the upstream provider.
Image Generation
Use /v1/images/generations to send a text-to-image request.
curl https://api.onemux.net/v1/images/generations \
-H "Authorization: Bearer $ONEMUX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_IMAGE_MODEL_ID",
"prompt": "一只坐在窗边的橘猫,午后自然光,写实摄影风格",
"size": "1024x1024",
"quality": "medium"
}'
Common parameters:
| Parameter | Required | Description |
|---|---|---|
model | Yes | ID of a currently available image model |
prompt | Yes | Description of the image content |
size | No | Image size; supported range depends on the model |
quality | No | Image quality; supported values depend on the model |
n | No | Number of images to generate; supported range depends on the model |
response_format | No | b64_json or url; available only for supported models |
background | No | Transparent or opaque background; available only for supported models |
output_format | No | png, jpeg, or webp; available only for supported models |
Do not use parameters supported by one model with other image models. If you encounter model_not_found, invalid_model, or an unsupported-parameter error, first verify the model ID and its capabilities.
Image Editing
Use /v1/images/edits to edit an existing image. Common OpenAI-compatible image models use multipart/form-data to upload images:
curl https://api.onemux.net/v1/images/edits \
-H "Authorization: Bearer $ONEMUX_API_KEY" \
-F "model=YOUR_IMAGE_MODEL_ID" \
-F "image[]=@input.png" \
-F "prompt=将背景改为浅蓝色,保持主体和文字不变" \
-F "size=1024x1024"
You can pass multiple reference images by repeating image[], for example:
-F "image[]=@person.png" \
-F "image[]=@product.png"
The supported number and format of images, masks, reference image URLs, and JSON editing formats depend on the model and upstream provider. Use these parameters only when explicitly supported by the model.
Python Usage
from openai import OpenAI
import os
client = OpenAI(
api_key=os.environ["ONEMUX_API_KEY"],
base_url="https://api.onemux.net/v1",
)
result = client.images.generate(
model="YOUR_IMAGE_MODEL_ID",
prompt="一张简洁的蓝色科技风产品海报",
size="1024x1024",
)
print(result.data[0].b64_json or result.data[0].url)
Image editing usually requires submitting multipart files directly. If your current Python SDK version does not support the editing parameters for the target model, use the cURL request above.
Response
Successful responses usually include a data array:
{
"created": 1760000000,
"data": [
{
"b64_json": "iVBORw0KGgo..."
}
]
}
Some models return an image URL when response_format is set to url:
{
"created": 1760000000,
"data": [
{
"url": "https://example.com/generated-image.png"
}
]
}
For Base64 responses, save the file in the actual image format. For URL responses, download and save the image promptly to avoid expiration of the temporary URL.
Billing
Image models do not use a single, unified Token-based billing method. OneMux bills according to the current pricing rules published for each model, which may include:
- Charges per generated image
- Charges based on image resolution or quality tier
- Charges based on image input, output Tokens, or other upstream usage
Refer to the current details for the corresponding model in the model catalog for actual prices, billing units, and supported specifications. Failed requests usually do not incur the image charges associated with successful results, but actual behavior depends on what is shown on the page and returned by the server.
FAQ
Why can't I use the chat API to generate images?
Image models use a dedicated Images route. Sending requests to /v1/chat/completions or another incompatible endpoint may result in an unsupported-endpoint or parameter error.
Why can I look up a model name but still have my request fail?
Check whether the model supports image generation or editing, whether your current API Key has permission, whether the request parameters are supported by the model, and whether the corresponding upstream provider is available.
Why is the response Base64 instead of an image link?
The model or response_format setting determines the response format. When you receive b64_json, decode and save it on the client. When you receive url, download the returned URL.
What should I do if image generation is slow?
High-resolution, high-quality, or complex editing requests may take longer. Set a reasonable request timeout on the client. Do not resubmit the same request just because the client timed out, as this may create duplicate tasks or charges.
GPT Image 2.6: SVG, GIF, and Complexity
The GPT Image 2.6 series adds SVG output, animated GIF output, and the complexity parameter. These capabilities are available only with models and upstream providers that support them.
SVG Output
SVG is for image generation, not image editing. When calling the generation endpoint, set output_format to svg and set n to 1. The image data in the response is Base64; decode it and save it as an .svg file.
{
"model": "YOUR_GPT_IMAGE_2_6_MODEL_ID",
"prompt": "一个简洁的蓝色几何图形标志",
"output_format": "svg",
"n": 1
}
Some upstream configurations may also require an additional svg object, such as svg.model. Add it only when the model or provider documentation explicitly requires it. Not all image models and providers support SVG.
Animated GIF Output
GPT Image 2.6 models that support this capability can set output_format to gif in the image generation endpoint. If supported by the model, use frame_count and frame_duration_ms to set the number of animation frames and the duration of each frame. GIF is a generation capability; do not assume the image editing endpoint can also return GIFs.
{
"model": "YOUR_GPT_IMAGE_2_6_MODEL_ID",
"prompt": "一只蓝色小鸟循环拍打翅膀的动画",
"output_format": "gif",
"frame_count": 6,
"frame_duration_ms": 200
}
Complexity Parameter
The GPT Image 2.6 series supports complexity: low, medium, and high. Try lower complexity for simple edits and higher complexity for images with dense text or complex layouts. This is a separate parameter from quality, and higher complexity may increase generation time.
{
"model": "YOUR_GPT_IMAGE_2_6_MODEL_ID",
"prompt": "一张细节丰富的城市街景编辑插画",
"complexity": "high",
"quality": "high"
}
These parameters are not supported by all models. If the API reports an unsupported-parameter error, remove the optional parameter or verify the capabilities of the selected model and provider.