For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs.
跳至內容

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:

  • 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:

<width>x<height>

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:

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

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:

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.

🕘 View Recent Generated Images

You can retrieve your recent successful image generation records with:

GET /v1/images

Example:

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:

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:

最後更新於

這有幫助嗎?