Spark Edit Portrait

API Tips

Input images must meet the following requirements:

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

File size: Maximum 5 MB

Image resolution: Maximum 4096 * 4096

Subject requirement: To ensure processing quality, input images must contain exactly 1 face. The face should preferably be frontal, unobstructed, and occupy a relatively high proportion of the image area. If these conditions are not met, processing quality will be poor

---

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_portrait

---

image_input string required

Image URL

Example: https://example.com/image.png

---

prompt string

Image generation prompt

Default: Concert group photo, flash photography

---

width integer

Width of the generated image

Range: 512-2048

Default: 1328

---

height integer

Height of the generated image

Range: 512-2048

Default: 1328

---

gpen number

HD processing effect. Higher values result in clearer faces. It is recommended to use the default value

Options: 0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1

Default: 0.4

---

skin number

Face beautification effect. Higher values result in more obvious beautification. It is recommended to use the default value

Options: 0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1

Default: 0.3

---

skin_unifi number

Skin uniformity effect. Higher values result in more uniform skin tone and blemish removal. It is recommended to use the default value

Options: 0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1

Default: 0

---

gen_mode string

Reference mode

creative: Prompt mode (automatically switches to this mode when prompt is provided). Only references the gender characteristics of the person
reference: Full reference mode (automatically switches to this mode when no prompt is provided). References more dimensions of the person (gender, clothing, hairstyle, etc.) and background
reference_char: Character reference mode. References more dimensions of the person (gender, clothing, hairstyle, etc.) but does not reference the background

Manual input takes priority over automatic switching

Options: creative, reference, reference_char

---

seed string

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)

---

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 (processed and uploaded to CDN)

size integer

Image size in bytes

jobId string

Remote task 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
0	No error
003010001	Missing image input
003010002	Invalid parameter
003010003	Invalid image format, only JPG/JPEG/PNG supported
003010095	Internal generation error
003010096	Result parsing error
003010097	HTTP error response
003010098	Status check error
003010099	Task creation error