Spark Dream 4.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 to use for the request

Value: spark_dream_4_0

---

prompt string required

Prompt for image generation, supports both Chinese and English

Recommended not to exceed 300 Chinese characters or 600 English words. Too many characters may cause information dispersion, and the model may ignore details, focusing only on key points, resulting in missing elements in the image

---

image string | array

Input image information, supports URL or Base64 encoding, supports single or multiple image input

Image URL: Ensure the image URL is accessible
Base64 encoding: Follow this format data:image/<image_format>;base64,<Base64_encoding>. Note that <image_format> should be lowercase, e.g., data:image/png;base64,<base64_image>

Image requirements:
Supported formats: JPEG, PNG, WebP, BMP, TIFF, GIF
Aspect ratio (width/height) range: 1/16 to 16
Width and height (px) > 14
Size: not exceeding 10MB
Total pixels: not exceeding 6000x6000=36000000 px (limit on the pixel product of single image width and height, not on individual width or height values)
Maximum 14 reference images supported

---

size string

Specify the size information of the generated image. Supports two methods, cannot be mixed

Method 1: Specify the resolution of the generated image, and describe the aspect ratio, shape, or usage in the prompt using natural language
Available values: 1K, 2K, 4K

Method 2: Specify the width and height pixel values
Total pixel range: 1280x720=921600 to 4096x4096=16777216
Aspect ratio range: 1/16 to 16

When using Method 2, both the total pixel range and aspect ratio range must be satisfied. Total pixels is a limit on the pixel product of single image width and height, not on individual width or height values

Valid example: 1600x600
Total pixel value 1600x600=960000, meets the range requirement [921600, 16777216]. Aspect ratio 1600/600=8/3, meets the range requirement [1/16, 16], so this example value is valid

Invalid example: 800x800
Total pixel value 800x800=640000, does not meet the minimum requirement 921600. Aspect ratio 800/800=1, although meets the range requirement [1/16, 16], but because it does not satisfy both constraints simultaneously, this example value is invalid

Recommended width and height pixel values:
1:1: 2048x2048
4:3: 2304x1728
3:4: 1728x2304
16:9: 2560x1440
9:16: 1440x2560
3:2: 2496x1664
2:3: 1664x2496
21:9: 3024x1296

Default: 2048x2048

---

sequential_image_generation string

Control whether to disable the image group feature

Image group: A set of content-related images generated based on your input

auto: Automatic mode, the model will determine whether to return image groups and the number of images based on the prompt
disabled: Disable image group feature, the model will only generate one image

Options: auto, disabled

Default: disabled

---

sequential_image_generation_options object

Configuration for image group feature. Only effective when sequential_image_generation is auto

max_images integer

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

The actual number of images that can be generated is also affected by the number of input reference images. Number of input reference images + final generated images ≤ 15

Range: 1 to 15

Default: 15

---

stream boolean

Control whether to enable streaming output mode

false: Non-streaming output mode, returns all information at once after all images are generated
true: Streaming output mode, returns results for each image immediately. Streaming output mode is effective for both single image and image group scenarios

Options: true, false

Default: false

---

response_format string

Specify the return format of the generated image

Generated images are in JPEG format, supports the following two return methods:

url: Returns image download link. Link is valid for 24 hours after image generation, please download images promptly
b64_json: Returns image data in Base64 encoded JSON format

Options: url, b64_json

Default: url

---

watermark boolean

Whether to add watermark to the generated image

false: No watermark
true: Add “AI Generated” watermark in the bottom right corner

Options: true, false

Default: true

---

optimize_prompt_options object

Configuration for prompt optimization feature

mode string

Set the mode for prompt optimization feature

standard: Standard mode, higher quality content generation, longer processing time
fast: Fast mode, shorter processing time, general quality

Options: standard, fast

Default: standard

---

Polling

Since image generation takes time, you need to poll the task status after creation

The initial response returns the task ID and initial status. The actual generation results must be obtained through polling the task status endpoint

Response Format

error object

Error information. Only present when status is failed

code string

Error code

error_message string

Detailed error message

---

output array

Generation results. Only present when status is completed

content array

List of generated content

type string

Resource type

Value: image

url string

Generated content URL

---

usage object

Usage statistics. Only present when status is completed

cost string

Total cost in USD

discount number

Discount amount

---

metadata object

Metadata information

---

Error Codes

Error Code	Description
003012001	Model missing
003012002	Prompt missing
003012003	Invalid prompt length
003012004	Invalid image format
003012005	Invalid image size
003012007	Invalid sequential generation mode
003012009	Invalid response format
003012010	Too many images
003012011	Invalid size parameter
003012012	Invalid prompt optimization mode
003012095	Internal generation error
003012096	Result parsing error
003012097	HTTP error response
003012099	Service unavailable