> For the complete documentation index, see [llms.txt](https://docs.apismart.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apismart.ai/api-guides/image-generation-api.md). # 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: ```http Authorization: Bearer ``` For JSON requests, also include: ```http 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: ```bash curl https://gw.apismart.ai/v1/images/generations \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "doubao-seedream-5-0", "prompt": "A mountain village at sunrise, watercolor style, vertical composition", "size": "2K", "watermark": false }' ``` The `prompt` describes the image you want to generate. ### 📐 Image Size The `size` parameter supports two formats. #### Resolution Presets Available presets: * `2K` * `3K` * `4K` 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: `x` For example: `2048x2048` Exact dimensions must satisfy both: * Total pixel count: `3,686,400` to `16,777,216` * Aspect ratio: between `1:16` and `16: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`: ```bash curl https://gw.apismart.ai/v1/images/generations \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "doubao-seedream-5-0", "prompt": "Transform this image into a watercolor painting", "image": "https://example.com/input.jpg", "size": "2048x2048" }' ``` 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. ```bash curl https://gw.apismart.ai/v1/images/generations \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "doubao-seedream-5-0", "prompt": "Combine the character from the first image with the environment from the second image", "image": [ "https://example.com/character.png", "https://example.com/scene.jpg" ], "size": "2K" }' ``` 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. ```bash curl https://gw.apismart.ai/v1/images/generations \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "doubao-seedream-5-0", "prompt": "Create a four-image minimalist dashboard design series", "size": "2K", "sequential_image_generation": "auto", "sequential_image_generation_options": { "max_images": 4 } }' ``` 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: ```json { "stream": true } ``` Example: ```bash curl https://gw.apismart.ai/v1/images/generations \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -N \ -d '{ "model": "doubao-seedream-5-0", "prompt": "Create a minimalist product design sequence", "size": "2K", "sequential_image_generation": "auto", "sequential_image_generation_options": { "max_images": 6 }, "stream": true }' ``` The `-N` option prevents curl from buffering streamed output. For an overview of ApiSmart response patterns, see [**Response Modes**](/api-guides/response-modes.md). ### 📤 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: ```bash curl https://gw.apismart.ai/v1/images/edits \ -H "Authorization: Bearer " \ -F model="doubao-seedream-5-0" \ -F image="@character.png" \ -F prompt="Place the character in a cyberpunk environment" \ -F size="2K" \ -F response_format="url" ``` 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 | Parameter | Type | Required | Description | | ------------------------------------- | -------------- | :------: | ---------------------------------------------------------------- | | `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: | Requirement | Limit | | ------------------------ | ------------------------------- | | 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: ```json { "created": 1714000000, "data": [ { "url": "https://cdn.example.com/generated-image.jpg", "size": "2048x2048" } ], "usage": { "generated_images": 1, "output_tokens": 16384, "total_tokens": 16384 } } ``` Important response fields include: * `data[].url` — Generated image URL * `data[].size` — Generated image dimensions * `usage.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**](/models-and-pricing/model-pricing-and-billing.md). ### 🕘 View Recent Generated Images You can retrieve your recent successful image generation records with: `GET /v1/images` Example: ```bash curl "https://gw.apismart.ai/v1/images?page=1&page_size=20" \ -H "Authorization: Bearer " ``` Supported query parameters: | Parameter | Default | Description | | ----------- | ------: | ------------------------------------- | | `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: ```http Authorization: Bearer ``` #### 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 * `size` uses either a preset or exact dimensions * Your client timeout is at least 90 seconds * You understand how many images the request may generate ### ➡️ Next Steps Continue with: * [**Models and Model IDs**](/models-and-pricing/models-and-model-ids.md) — Find supported model IDs * [**Model Pricing and Billing**](/models-and-pricing/model-pricing-and-billing.md) — Understand image generation costs * [**Response Modes**](/api-guides/response-modes.md) — Understand synchronous and streaming responses * [**Usage Logs and Costs**](/api-usage/usage-logs-and-costs.md) — Review request-level usage and costs * [**HTTP Status Codes and API Errors**](/troubleshooting/http-status-codes-and-api-errors.md) — Troubleshoot API failures