Spark Image to Image 3.0

API Tips

Input Image Requirements

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

File size: Maximum 4.7 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 range is within [512, 1536]

For detailed width and height rules of output images, refer to the parameter descriptions in width and height below

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_i2i_3_0

prompt `string` required

Text prompt for editing the image.

Recommendations:

Recommended length: ≤120 characters, maximum 800 characters. Excessively long prompts may cause abnormal generation or no effect.
For design and marketing scenarios, include keywords like “poster, graphic design” in the prompt for enhanced results (e.g., “Graphic design, a puppy running on the street”).
Enclose text you want to appear in the image with quotes for higher accuracy (e.g., “A Christmas card with ‘Merry Christmas’ written on it”).
Use natural language for editing instructions.
Single instruction per edit works better.
For local edits, be precise in descriptions, especially when multiple entities are present. Clearly describe who to edit and what to do for more accurate results.
If editing effect is not obvious, adjust the scale parameter. Higher values follow instructions more closely.
Use clear, high-resolution input images for better results.

Example instructions:

Add/remove entities: Add/remove xxx (Remove the girl in the image / Add a rainbow)
Modify entities: Change xxx to xxx (Change the chicken leg in hand to a hamburger)
Modify style: Change to xxx style (Change to cartoon style)
Modify colors: Change xxx to xx color (Change the clothes to pink)
Modify actions: Modify expressions and actions (Make him cry/laugh/angry)
Modify environment/background: Change background to xxx, at xxx (Change background to beach / Under the starry sky)

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 used to determine the initial state of diffusion. Default: -1 (random).

If the seed is the same positive integer and all other parameters are identical, the generated content will have a very high probability of being consistent.

Default: -1

scale `number`

The degree of influence of the text description. Higher values mean greater influence from the text description and less influence from the input image.

Range: [0, 1]

Default: 0.5

width `integer`

Width of the generated image.

Default: System generates 1328 × 1328 images by default.

Custom dimensions: Supports custom width and height in the range [512, 2016].

Recommended aspect ratios:

1328 × 1328 (1:1)
1472 × 1104 (4:3)
1584 × 1056 (3:2)
1664 × 936 (16:9)
2016 × 864 (21:9)

Note: Both width and height must be provided together to take effect.

Default: 1328

height `integer`

Height of the generated image.

Important notes:

Both width and height must be provided together to take effect.
If both custom width and height are much smaller than 1024 (e.g., below 600), the output may be completely black. It’s recommended to set dimensions close to 1024.
The final output dimensions are related to but not exactly equal to the input dimensions. They will be the “closest multiple of 16” to the input dimensions, within the range [512, 1536].

Default: 1328

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 image content.

type string

Resource type. Value: image

url string

Generated image URL.

size integer

File 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.

input_tokens integer

Number of input tokens.

output_tokens integer

Number of output tokens.

total_tokens integer

Total number of tokens.

generated_images integer

Number of generated images.

Error Codes

Error Code	Description
003003001	Prompt missing
003003002	Invalid prompt length
003003003	Image missing
003003004	Invalid image count
003003005	Invalid seed
003003006	Invalid scale factor
003003007	Invalid dimensions
003003008	Image source conflict
003003009	Invalid image array
003003095	Internal generation error
003003096	Result parsing error
003003097	HTTP error response
003003098	Status check error
003003099	Task creation error

curl --location 'https://cloud.vtrix.ai/model/v1/generation' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "model": "spark_i2i_3_0", "input": [ { "params": { "prompt": "Change the background to a beach scene", "image_urls": ["https://example.com/input-image.jpg"], "scale": 0.5, "width": 1328, "height": 1328 } } ] }'

{ "id": "d5u5obte8783ap44qtj0", "created_at": 1769757744021, "status": "completed", "model": "spark_i2i_3_0", "output": [ { "content": [ { "type": "image", "url": "https://example.com/generated-image.jpg", "size": "1024x1024" } ] } ], "usage": { "cost": "0.000500", "discount": 0 } }

API Tips

Input Image Requirements

Output Image Description

Authentication

authorization `string` required

Parameters

model `string` required

prompt `string` required

image_urls `array` required (one of two)

binary_data_base64 `array` required (one of two)

seed `integer`

scale `number`

width `integer`

height `integer`

Polling

Response Format

error `object`

code `string`

error_message `string`

output `array`

content `array`

type `string`

url `string`

size `integer`

jobId `string`

usage `object`

cost `string`

discount `number`

input_tokens `integer`

output_tokens `integer`

total_tokens `integer`

generated_images `integer`

Error Codes

API Tips

Input Image Requirements

Output Image Description

Authentication

authorization string required

Parameters

model string required

prompt string required

image_urls array required (one of two)

binary_data_base64 array required (one of two)

seed integer

scale number

width integer

height integer

Polling

Response Format

error object

code string

error_message string

output array

content array

type string

url string

size integer

jobId string

usage object

cost string

discount number

input_tokens integer

output_tokens integer

total_tokens integer

generated_images integer

Error Codes

authorization `string` required

model `string` required

prompt `string` required

image_urls `array` required (one of two)

binary_data_base64 `array` required (one of two)

seed `integer`

scale `number`

width `integer`

height `integer`

error `object`

code `string`

error_message `string`

output `array`

content `array`

type `string`

url `string`

size `integer`

jobId `string`

usage `object`

cost `string`

discount `number`

input_tokens `integer`

output_tokens `integer`

total_tokens `integer`

generated_images `integer`