Spark Dream 5.0 Flash | Vtrix API Docs

API Notes

spark_dream_5_0_flash supports text-to-image generation, single-image editing, and up to 10 reference images; ordinary generation returns 1 image per request

spark_dream_5_0_flash parameters belong in input[0].params; the wrapper returns platform-hosted image URLs and does not support Base64 output

spark_dream_5_0_flash does not support stream, sequential_image_generation, sequential_image_generation_options, tools, or optimize_prompt_options.mode: "fast"

spark_dream_5_0_flash decomposition accepts exactly 1 PNG or JPEG and returns a base image plus up to 16 layers

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

Customer-facing model ID

Value: spark_dream_5_0_flash

input `array` required

Provide one object containing params; all model parameters below belong in input[0].params

prompt `string`

Required for ordinary generation and reference-image editing; optional for decomposition, which automatically identifies the main elements when omitted
Recommended length: no more than 300 Chinese characters or 600 English words

image `string` | `array`

An accessible image URL or Base64 Data URI in the format data:image/<format>;base64,<content>, using a lowercase format name
Omit for text-to-image generation; provide one image for editing or 2 to 10 images for reference-image generation
Ordinary input supports jpeg, png, webp, bmp, tiff, gif, heic, and heif; each image must be at most 30 MB, both dimensions greater than 14 pixels, total pixels at most 36,000,000, and aspect ratio from 1/16 to 16
Decomposition requires exactly one PNG or JPEG with 262,144 to 36,000,000 total pixels and the same file size and aspect ratio limits

layer_decomposition `boolean`

Decomposes the input into one base image and up to 16 independent layers, each a PNG with an alpha channel
If any layer fails, the entire request fails without partial results; requesting more layers than the limit may omit some elements

Default: false

size `string`

For ordinary generation, use a resolution level or widthxheight; custom dimensions must satisfy both 921,600 to 4,624,220 total pixels and an aspect ratio from 1/16 to 16
Decomposition accepts only resolution levels or auto, not custom dimensions; the base preserves the input aspect ratio and each layer preserves its corresponding region’s aspect ratio
auto handles the base and each layer separately: preserve original dimensions within the pixel range above, resize smaller images to 1K, and larger images to 2K

Ordinary generation options: 1K, 1.5K, 2K, or valid dimensions
Ordinary generation default: 2K
Decomposition options: 1K, 1.5K, 2K, auto
Decomposition default: auto

Common reference dimensions:

Resolution	1:1	4:3	3:4	16:9	9:16	3:2	2:3	21:9
`1K`	`1024x1024`	`1152x864`	`864x1152`	`1424x800`	`800x1424`	`1248x832`	`832x1248`	`1568x672`
`1.5K`	`1536x1536`	`1792x1344`	`1344x1792`	`2048x1152`	`1152x2048`	`1872x1248`	`1248x1872`	`2352x1008`
`2K`	`2048x2048`	`2368x1776`	`1776x2368`	`2816x1584`	`1584x2816`	`2496x1664`	`1664x2496`	`3136x1344`

optimize_prompt_options `object`

Prompt optimization settings

mode string

Standard prompt optimization; fast is not supported

Options: standard
Default: standard

output_format `string`

Output format for ordinary generation; in decomposition it controls only the base image, while all layers are PNG

Options: png, jpeg
Default: jpeg

background `string`

Controls whether the output image has a transparent background
Transparent-background editing requires exactly one input image with an alpha channel; explicitly set output_format: "png", as JPEG input or output does not meet this requirement
Transparent mode defaults to PNG when the output format is omitted; ordinary PNG or JPEG decomposition does not require background: "transparent"

Options: opaque, transparent
Default: opaque

response_format `string`

The wrapper always returns platform-hosted image URLs; other values do not enable Base64 output

Value: url

watermark `boolean`

Whether to add an AI-generated watermark to the lower-right corner

Default: true

Request Examples

The text-to-image example on the right uses POST /model/v1/generation. Reference URLs below are placeholders; replace them with accessible images before calling

Reference-image editing

curl --location 'https://cloud.vtrix.ai/model/v1/generation' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
    "model": "spark_dream_5_0_flash",
    "input": [{"params": {
      "prompt": "Change the background to pale green and keep the main subject",
      "image": "https://example.com/reference.png",
      "size": "1K",
      "output_format": "png",
      "watermark": false
    }}]
  }'

Layer decomposition

curl --location 'https://cloud.vtrix.ai/model/v1/generation' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
    "model": "spark_dream_5_0_flash",
    "input": [{"params": {
      "image": "https://example.com/source.png",
      "prompt": "Separate the title, foreground subject, and background",
      "layer_decomposition": true,
      "size": "auto",
      "output_format": "png",
      "watermark": false
    }}]
  }'

Synchronous request

The synchronous endpoint uses the same request body and waits for completion before returning results; allow sufficient client request timeout for generation

curl --location 'https://cloud.vtrix.ai/model/v1/generation/sync' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
    "model": "spark_dream_5_0_flash",
    "input": [{"params": {
      "prompt": "A red circle on a white background",
      "size": "1K",
      "output_format": "png",
      "watermark": false
    }}]
  }'

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.

In an asynchronous create response, status: "completed" means the create request completed, not that image generation finished. Replace task_id in the query URL with the returned id, and read results once the query returns completed with output

Task query status	Meaning
`in_progress`	Continue querying the same task
`completed`	Read `output[].content[]`
`failed`	Read `error.code` and `error.message`

Response Format

Images and usage

Field	Type	Description
`output[].content[].type`	string	`image`
`output[].content[].url`	string	Platform-hosted image URL
`output[].content[].size`	string	Actual dimensions when returned, such as `1024x1024`
`output[].content[].output_format`	string	`png` or `jpeg` when returned
`usage.input_images`	number	Input image count, when returned
`usage.generated_images`	number	Successful output count, including the base and all layers
`usage.quantity`	number	Billable quantity
`usage.cost`	string	Request cost in USD
`metadata`	object	Task timing and other metadata, when returned

Layer fields

Field	Type	Description
`z_index`	integer	`0` for the base; layers start at `1`, with higher values on top
`name`	string	Layer name
`description`	string	Layer content description
`bounding_box.absolute`	integer[4]	`[left, top, right, bottom]` in base-image coordinates; omitted for the base
`bounding_box.normalized`	integer[4]	The same bounds normalized to `[0, 1000]`; omitted for the base

Illustrative response with a base and one layer, showing relevant fields only and placeholder URLs:

{
  "id": "task_id",
  "status": "completed",
  "model": "spark_dream_5_0_flash",
  "output": [{"content": [
    {
      "type": "image",
      "url": "https://example.com/base.png",
      "size": "1024x1024",
      "output_format": "png",
      "z_index": 0,
      "name": "base",
      "description": "Base image"
    },
    {
      "type": "image",
      "url": "https://example.com/title.png",
      "size": "2048x512",
      "output_format": "png",
      "z_index": 1,
      "name": "title",
      "description": "Title layer",
      "bounding_box": {
        "absolute": [128, 64, 896, 256],
        "normalized": [125, 63, 875, 250]
      }
    }
  ]}],
  "usage": {
    "input_images": 1,
    "generated_images": 2,
    "quantity": 2,
    "cost": "0.036"
  }
}

To reconstruct, resize each layer to (right - left) x (bottom - top), place it at (left, top), and stack in ascending z_index order
For a custom W x H canvas, multiply normalized horizontal coordinates by W / 1000 and vertical coordinates by H / 1000

Pricing

The base rate is 0.018 USD per successfully output image; input images are free and dimensions do not change this base rate. Actual cost depends on applicable discounts and the final usage.cost

Scenario	Successful outputs	Base cost
Ordinary generation or editing	`1` image	`0.018 USD`
Base plus `7` layers	`8` images	`0.144 USD`

Failed requests without successful outputs incur no image-generation charge. Both the base and every layer count as outputs

In the current decomposition response, usage.unit_price is a compatibility field containing the aggregate amount; do not multiply it by the output count again. Read cost from usage.cost and output count from usage.generated_images

Error Handling

For failed tasks, read error.code and error.message. Check the prompt, image accessibility, format and dimensions, transparent-background requirements, and decomposition input count; wrapper errors do not guarantee the underlying API’s specific error code

API Notes

Authentication

authorization string required

Parameters

model string required

input array required

prompt string

image string | array

layer_decomposition boolean

size string

optimize_prompt_options object

mode string

output_format string

background string

response_format string

watermark boolean