Spark Dream 5.0 Pro | Vtrix API Docs

API notes

Standard generation returns one image. Sequential image generation is not supported.
Streaming output and web search tools are not supported.
Layer decomposition accepts exactly one PNG or JPEG image and returns one base image plus up to 16 editable PNG layers.
Result URLs are hosted by the platform. Only URL responses are supported.

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 used for the request.

Value: spark_dream_5_0_pro

prompt `string`

Describes the image to generate or the elements to separate into layers.

Required for standard image generation. Optional for layer decomposition; when omitted, the model automatically identifies the main elements in the input image.

Chinese prompts should be no more than 300 characters and English prompts no more than 600 words. The model also supports Russian, Arabic, Filipino, Thai, Turkish, Korean, Malay, Spanish, Portuguese, Indonesian, French, German, Vietnamese, and Japanese prompts.

image `string` | `array`

Input image URL or Base64 data URI in the format data:image/<format>;base64,<content>.

For standard generation:

Omit image for text-to-image generation.
Pass one image for single-image editing.
Pass 2 to 10 images for multi-reference generation.
Supported formats: jpeg, png, webp, bmp, tiff, gif, heic, and heif.
Each image must be no larger than 30 MB, have an aspect ratio between 1/16 and 16, and contain no more than 36,000,000 pixels.

For layer decomposition, image is required and must contain exactly one PNG or JPEG image. The image must be no larger than 30 MB, have an aspect ratio between 1/16 and 16, and contain between 262,144 and 36,000,000 pixels.

layer_decomposition `boolean`

Enables layer decomposition.

false: standard image generation.
true: separates the input into one base image and up to 16 independently editable layers.

Default: false

Every separated layer is a PNG image with an alpha channel. If any layer fails, the entire request fails rather than returning a partial result.

size `string`

For standard generation, use a resolution preset or an exact widthxheight value.

Presets: 1K, 1.5K, 2K.
Default: 2K.
Custom dimensions must contain between 921,600 and 4,624,220 pixels and have an aspect ratio between 1/16 and 16.

Common preset dimensions:

Preset	1:1	4:3	3:4	16:9	9:16
`1K`	`1024x1024`	`1152x864`	`864x1152`	`1424x800`	`800x1424`
`1.5K`	`1536x1536`	`1792x1344`	`1344x1792`	`2048x1152`	`1152x2048`
`2K`	`2048x2048`	`2368x1776`	`1776x2368`	`2816x1584`	`1584x2816`

For layer decomposition, only 1K, 1.5K, 2K, and auto are supported. The default is auto, which preserves eligible source dimensions and otherwise scales each result toward the supported 1K-to-2K range while preserving its aspect ratio.

optimize_prompt_options `object`

Prompt optimization settings.

mode accepts:

standard: prioritizes output quality.
fast: reduces processing time with a slight quality tradeoff.

Default: standard

output_format `string`

Output format for the generated image or layer-decomposition base image.

Options: png, jpeg

Default: jpeg

In layer decomposition mode, this field controls only the base image. Individual layers are always returned as PNG files.

background `string`

Controls whether the output has a transparent background.

opaque: generates a normal opaque background.
transparent: generates an image with an alpha channel.

Default: opaque

Transparent output is supported only for image-to-image requests with exactly one alpha-capable input image. Use output_format: "png"; JPEG output is not compatible with transparency.

response_format `string`

Response format. The platform always returns hosted image URLs.

Value: url

watermark `boolean`

Whether to add an “AI generated” watermark in the lower-right corner.

Default: true

Layer decomposition example

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_pro",
    "input": [
      {
        "params": {
          "image": "https://example.com/source-with-alpha.png",
          "prompt": "Separate the title, foreground product, and background",
          "layer_decomposition": true,
          "size": "auto",
          "output_format": "png",
          "background": "transparent",
          "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.

Response format

Standard fields

Field	Type	Description
`error`	object	Error details. Present only when `status` is `failed`.
`output`	array	Output groups containing generated image items in `content`.
`usage`	object	Usage statistics. Present after successful completion.
`metadata`	object	Task timing and additional metadata.

Each image item contains type, url, size, and output_format when provided by the model.

Layer fields

Layer decomposition adds these fields to each image item:

Field	Type	Description
`z_index`	integer	Stacking order. The base image is `0`; layers start at `1`, with larger values placed above smaller values.
`name`	string	Model-generated layer name.
`description`	string	Model-generated description of the layer content.
`bounding_box.absolute`	integer[4]	Pixel coordinates `[left, top, right, bottom]` in the base-image coordinate system. Not returned for the base image.
`bounding_box.normalized`	integer[4]	The same bounds normalized to the integer range `[0, 1000]`. Not returned for the base image.

Example completed result:

{
  "id": "d5u5obte8783ap44qtj0",
  "created_at": 1788451200000,
  "status": "completed",
  "model": "spark_dream_5_0_pro",
  "output": [
    {
      "content": [
        {
          "type": "image",
          "url": "https://example.com/base.png",
          "size": "2048x2048",
          "output_format": "png",
          "z_index": 0,
          "name": "base",
          "description": "Base image"
        },
        {
          "type": "image",
          "url": "https://example.com/title.png",
          "size": "1024x256",
          "output_format": "png",
          "z_index": 1,
          "name": "title",
          "description": "Title layer",
          "bounding_box": {
            "absolute": [180, 64, 812, 198],
            "normalized": [88, 31, 396, 97]
          }
        }
      ]
    }
  ],
  "usage": {
    "input_images": 1,
    "generated_images": 2,
    "output_tokens": 23107,
    "total_tokens": 23107
  }
}

To restore a layer with absolute coordinates, place it at (left, top) after resizing it to (right - left) x (bottom - top). Composite multiple layers in ascending z_index order.

For a custom canvas of size W x H, convert normalized coordinates with:

x = left / 1000 * W
y = top / 1000 * H
width = (right - left) / 1000 * W
height = (bottom - top) / 1000 * H

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_pro", "input": [ { "params": { "prompt": "A clean editorial poster for a summer music festival, bold geometric typography, vivid cyan and coral accents, studio lighting, premium graphic design", "size": "2K", "optimize_prompt_options": { "mode": "fast" }, "output_format": "png", "watermark": false } } ] }'

{ "id": "d5u5obte8783ap44qtj0", "created_at": 1788451200000, "status": "completed", "model": "spark_dream_5_0_pro", "output": [ { "content": [ { "type": "image", "url": "https://example.com/generated-image.png", "size": "2048x2048", "output_format": "png" } ] } ] }

API notes

Authentication

authorization string required

Parameters

model string required

prompt string

image string | array

layer_decomposition boolean

size string

optimize_prompt_options object

output_format string

background string

response_format string

watermark boolean