Image Generation API
Learn how to generate and edit images with ApiSmart using text prompts, reference images, multi-image inputs, sequential generation, streaming, and local file uploads.
Use the Image Generation API to create and transform images with supported ApiSmart image models.
The API supports text-to-image, image-to-image, multiple reference images, sequential image generation, streaming output, and local image uploads.
🖼️ Endpoint
Method: POST
Endpoint: /v1/images/generations
Full URL:
https://gw.apismart.ai/v1/images/generations
Current image model:
doubao-seedream-5-0
🔑 Authentication
Include your ApiSmart API Key in the Authorization header:
Authorization: Bearer <your-api-key>For JSON requests, also include:
Content-Type: application/json⏱️ Request Timeout
Image generation is synchronous by default.
The connection remains open until image generation finishes and the result is returned.
A single image typically takes approximately 20–40 seconds. High-resolution generation, multiple reference images, or sequential generation may take longer.
Set your client timeout to at least:
90 seconds
If your client disconnects too early, the generation may still complete and incur a charge even though your application does not receive the result.
🚀 Text-to-Image
Send a text prompt to generate an image:
The prompt describes the image you want to generate.
📐 Image Size
The size parameter supports two formats.
Resolution Presets
Available presets:
2K3K4K
When using a preset, you can describe the desired composition or aspect ratio in the prompt.
For example:
A cinematic coastal city at sunset, horizontal 16:9 composition
Exact Pixel Dimensions
You can also provide exact dimensions:
<width>x<height>
For example:
2048x2048
Exact dimensions must satisfy both:
Total pixel count:
3,686,400to16,777,216Aspect ratio: between
1:16and16:1
Do not combine a resolution preset and exact pixel dimensions in the same size value.
🔄 Image-to-Image
To use an existing image as a reference, provide its URL using image:
The reference image must meet the supported image input requirements.
🧩 Multiple Reference Images
You can provide multiple images using an array.
Up to 14 reference images are supported.
This can be used for workflows such as character references, product combinations, or visual composition.
🖼️ Sequential Image Generation
Use sequential generation when you want multiple related images from one request.
Set:
sequential_image_generation: "auto"
to enable sequential generation.
max_images accepts values from 1 to 15.
The total number of input and generated images must not exceed the supported combined limit.
🌊 Streaming Image Output
Image generation also supports SSE streaming.
Set:
Example:
The -N option prevents curl from buffering streamed output.
For an overview of ApiSmart response patterns, see Response Modes.
📤 Upload a Local Image
To upload a local image file instead of using a public image URL, use the Image Edits endpoint:
Method: POST
Endpoint: /v1/images/edits
Example:
This endpoint uses multipart form data rather than a JSON request body.
Each uploaded image file must be no larger than 10 MB, and up to 14 reference images are supported.
⚙️ Parameters
model
string
Yes
Image model ID. Currently doubao-seedream-5-0.
prompt
string
Yes
Image generation instruction. Chinese and English are supported.
image
string / array
No
Reference image URL or array of URLs. Up to 14 images.
size
string
No
2K, 3K, 4K, or exact dimensions such as 2048x2048.
response_format
string
No
Response format. Currently url.
watermark
boolean
No
Controls the AI-generated watermark. Default: true.
sequential_image_generation
string
No
Use "auto" to enable sequential image generation.
sequential_image_generation_options
object
No
Sequential generation options, including max_images.
tools
array
No
Optional tools, such as web search where supported.
stream
boolean
No
Set to true to enable SSE streaming. Default: false.
output_format
string
No
png or jpeg. Default: jpeg.
seed
integer
No
Random seed.
optimize_prompt_options
object
No
Optional prompt optimization settings.
📋 Reference Image Requirements
Reference images must meet the following requirements:
Supported formats
JPEG, PNG, WebP, BMP, TIFF, GIF
Maximum file size
10 MB per image
Minimum width / height
Greater than 14 px
Maximum total pixels
36,000,000
Supported aspect ratio
1:16 to 16:1
Maximum reference images
14
Input + generated images
Maximum 15
Requests that exceed these limits may be rejected.
📦 Successful Response
A successful response can look like:
Important response fields include:
data[].url— Generated image URLdata[].size— Generated image dimensionsusage.generated_images— Number of generated images reported in the response
Generated image URLs returned directly by the generation endpoint are temporary. Save important images to your own storage.
💰 Billing
Image generation is currently billed per generated image.
For doubao-seedream-5-0:
$0.04 / image
The final charge is based on the number of actual image results delivered and deduplicated for billing.
For URL responses, the delivered image count is normally based on valid image results returned in data[].
This means that multi-image and sequential-generation requests may cost more than a single-image request.
For billing details, see Model Pricing and Billing.
🕘 View Recent Generated Images
You can retrieve your recent successful image generation records with:
GET /v1/images
Example:
Supported query parameters:
page
1
Page number
page_size
20
Number of records per page, up to 100
A history record can include information such as:
Generation ID
Model ID
Generated image URLs
Image count
Resolution
Cost
Creation time
Storage status
Only the most recent 7 days of image history can be queried through this endpoint.
Save important generated images to your own storage rather than relying on history availability.
⚠️ Common Issues
Invalid API Key
401 invalid_api_key
Verify that your API Key is valid and that the request includes:
Model Not Available
403 model_not_allowed
The image model is not currently enabled for your API Key or account.
Unsupported Model
403 model_not_image_capable
The selected model does not support the image generation endpoint.
Invalid Parameters
A 400 response can indicate invalid JSON, unsupported parameters, or invalid image configuration.
Check the request body, image limits, and size value.
Request Timeout
Image generation may take longer than ordinary text requests.
Set your client timeout to at least 90 seconds and avoid immediately retrying a request simply because the client timed out.
✅ Before Sending a Request
Verify that:
Your API Key is valid and enabled
Your account has sufficient balance
The model ID is correct
The endpoint matches the image workflow
Reference images meet the supported limits
sizeuses either a preset or exact dimensionsYour client timeout is at least 90 seconds
You understand how many images the request may generate
➡️ Next Steps
Continue with:
Models and Model IDs — Find supported model IDs
Model Pricing and Billing — Understand image generation costs
Response Modes — Understand synchronous and streaming responses
Usage Logs and Costs — Review request-level usage and costs
HTTP Status Codes and API Errors — Troubleshoot API failures
最後更新於
這有幫助嗎?