Spark Edit 3.0 (Will be deprecated)

API Tips

Input Image Requirements

Supported formats: JPEG, PNG only (JPEG format recommended)

File size: Maximum 5 MB

Image resolution: Maximum 4096 * 4096

Aspect ratio: The ratio of the long side to the short side must be within 3. Exceeding this ratio or using extreme aspect ratios will result in errors

Output Image Description

Output image resolution is related to the input image aspect ratio, not the original resolution size

The final output image aspect ratio is close to the original image, with single side length: [512, 1536]

---

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_edit_3_0

---

prompt string required

Prompt for image editing

Recommended length ≤ 120 characters, maximum 800 characters. Prompts that are too long may cause abnormal results or not take effect

Editing instructions can use natural language
Single instruction per edit works better
For local editing, describe precisely especially when there are multiple entities in the image - describe clearly who does what for more precise editing effects
If editing effect is not obvious, adjust the scale parameter - higher values will follow instructions more closely
Use clear, high-resolution images. Images generated by Doubao model have better editing effects

Reference examples:
Add/Remove entity: Add/Remove xxx (remove the girl in the picture / add a rainbow)
Modify entity: Change xxx to xxx (change the drumstick in hand to a burger)
Modify style: Change to xxx style (change to comic style)
Modify color: Change xxx to xx color (change the clothes to pink)
Modify action: Modify expression/action (make him cry/smile/angry)
Modify background: Change background to xxx, at xxx (change background to beach / under the stars)

---

image_urls array required (one of two)

Image file URLs. Requires 1 input image

Either image_urls or binary_data_base64 must be provided (one of two)

---

binary_data_base64 array required (one of two)

Image files in Base64 encoding. Requires 1 input image

Either image_urls or binary_data_base64 must be provided (one of two)

---

seed integer

Random seed as the basis for determining the initial diffusion state. If the random seed is the same positive integer and other parameters are consistent, the generated content will most likely have consistent results

Default: -1 (random)

---

scale number

Affects the degree of text description influence. Higher values mean greater text description influence and lower input image influence

Range: 0-1

Default: 0.5

---

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

Image URL

size integer

Image size in bytes

jobId string

Remote job ID

---

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
3007001	Missing prompt
3007002	Missing image
3007003	Invalid image format
3007004	Invalid prompt length
3007005	Invalid image size
3007006	Invalid parameter
3007007	Authentication failed
3007008	Invalid image array
3007009	Invalid image element
3007095	Internal generation error
3007096	Result parsing error
3007097	HTTP error response
3007098	Status check error
3007099	Service unavailable