Spark Dream 5.0

Authentication

authorization string required

All APIs require authentication via Bearer Token.

Get API Key:

Visit API Key Management Page to get your API Key.

Usage:

Add to request header:

Authorization: Bearer YOUR_API_KEY

Parameters

model string required

Model ID used for the request

Value: spark_dream_5_0

---

prompt string required

Prompt used for image generation. Supports both Chinese and English.

Recommended length is no more than 300 Chinese characters or 600 English words. If the text is too long, information can become diluted, and the model may focus only on key points while missing some details in the generated image.

---

image string | array

Input image information. Supports URL or Base64 encoding.

Image URL: make sure the URL is accessible.
Base64: use this format data:image/<image_format>;base64,<Base64_content>. Note that <image_format> must be lowercase, for example data:image/png;base64,<base64_image>.

Input images must meet the following requirements:
Image formats: jpeg, png, webp, bmp, tiff, gif
Aspect ratio (width/height): 1/16 to 16
Width and height (px): > 14
File size: up to 10MB
Total pixels: up to 6000x6000=36000000 px (limit applies to width × height of each single image, not width or height alone)
Up to 14 reference images are supported.

---

size string

Specifies output image size. Two methods are supported and cannot be mixed.

Method 1: Specify resolution, and describe desired aspect ratio, image shape, or use case in the prompt using natural language. The model determines the final output size.
Available values: 2K, 3K

Method 2: Specify exact width and height in pixels.
Total pixel range: 2560x1440=3686400 to 3072x3072x1.1025=10404496
Aspect ratio range: 1/16 to 16

When using Method 2, both the total-pixel range and the aspect-ratio range must be satisfied. Total pixels means width × height for a single image.

Valid example: 3750x1250
Total pixels 3750x1250=4687500, which is within [3686400, 10404496]; aspect ratio 3750/1250=3, which is within [1/16, 16]. So this value is valid.

Invalid example: 1500x1500
Total pixels 1500x1500=2250000, below the minimum 3686400; aspect ratio 1500/1500=1 is within [1/16, 16], but since both constraints are required, this value is invalid.

Recommended width and height values:

Resolution	Aspect Ratio	Width x Height
2K	1:1	2048x2048
2K	4:3	2304x1728
2K	3:4	1728x2304
2K	16:9	2848x1600
2K	9:16	1600x2848
2K	3:2	2496x1664
2K	2:3	1664x2496
2K	21:9	3136x1344
3K	1:1	3072x3072
3K	4:3	3456x2592
3K	3:4	2592x3456
3K	16:9	4096x2304
3K	9:16	2304x4096
3K	2:3	2496x3744
3K	3:2	3744x2496
3K	21:9	4704x2016

Default: 2048x2048

---

sequential_image_generation string

Controls whether image-group generation is disabled.

Image group: a set of related images generated from your input.
auto: the model automatically decides whether to return an image group and how many images to include.
disabled: disables image-group generation and returns only one image.

Options: auto, disabled

Default: disabled

---

sequential_image_generation_options object

Configuration for image-group generation. Only takes effect when sequential_image_generation is auto.

max_images integer

Specifies the maximum number of images that can be generated in this request.

Range: 1 to 15

The final number of generated images is affected by both max_images and the number of reference images. Number of reference images + number of generated images must be <= 15.

Default: 15

---

tools array<object>

Configures tools that the model can call.

This parameter is temporarily unavailable.

type string

Specifies the tool type.

web_search: online web retrieval.

When web retrieval is enabled, the model can decide whether to search internet content (for example, products or weather) based on the prompt, improving timeliness of generated images while adding some latency.

You can check actual search usage via usage.tool_usage.web_search. A value of 0 means no web search was used.

---

stream boolean

Controls whether streaming output mode is enabled.
false: non-streaming mode, returns all information only after all images are generated.
true: streaming mode, returns each image result as soon as it is available. Works for both single-image and image-group scenarios.

Options: true, false

Default: false

---

output_format string

Specifies the output image file format.

Options: png, jpeg

Default: jpeg

---

response_format string

Specifies the response format for generated images.
url: returns image download URLs; links remain valid for 24 hours after generation.
b64_json: returns image data in Base64-encoded JSON format.

Options: url, b64_json

Default: url

---

watermark boolean

Whether to add a watermark to generated images.
false: no watermark.
true: adds an “AI Generated” watermark in the bottom-right corner.

Options: true, false

Default: true

---

optimize_prompt_options object

Configuration for prompt optimization.

mode string

Sets the mode used by prompt optimization.

standard: standard mode, higher quality generation with longer processing time.

Options: standard

Default: standard

---

Polling

Since result generation takes time, you need to poll the task status after creating the task.

The initial response only returns information such as the task ID and initial status. The final result must be obtained by polling the task status endpoint using the task ID.

See the examples on the right for polling requests and responses.

Response Format

error object

Error information. Only appears when status is failed.

code string

Error code

error_message string

Detailed error message

---

output object

Generated output.

content array

List of generated images

type string

Resource type

Value: image

url string

Image URL

---

usage object

Usage statistics. Only appears when status is completed.

---

metadata object

Metadata information.