Submit Task (Vega Format)

Vega image generation runs as an async task: submit → poll → download the image. Submitting returns a task ID immediately without holding the connection open — ideal for batch submission, long-running generation, and centralized management in a task queue. Available models and current prices are subject to the Model Plaza.

Model IDDescription
wand-vega-image-liteVega Lite — cost-effective
wand-vega-image-flashVega Flash — fastest generation
wand-vega-image-proVega Pro — supports multiple reference images, highest quality
TIP

All three models share the same endpoint and request fields. Text-to-image and image-to-image use the same endpoint: omit input for text-to-image; include input for image-to-image.

NOTE

An async task pre-charges 0 at submission and settles against the usage actually returned by the upstream when the task completes (difference refunded or charged); failed tasks are not billed. Check the console's "Usage Logs" at any time.

WARNING

Generation usually takes 20–100 seconds (Lite about 19 s and Pro about 98 s in our tests). Allow at least 5 minutes of polling, with a 30-second timeout per poll request — see Query & Download.

Endpoint

POST /v1/tasks/vega

Authentication

Pass the Bearer token in the request header (see Base URL & Authentication):

Authorization: Bearer sk-your-token

Request Body

FieldTypeRequiredNotes
modelstringYesImage model name; see the model table above
promptstringRequired for t2iScene description; for image-to-image it is the redraw description, see Image-to-Image
sizestringNoImage size in widthxheight format, e.g. 1024x1024; the upstream default applies when omitted
nintegerNoFixed at 1 — Vega generates one image per call
inputarray[object]Required for i2iReference image array; see Image-to-Image
NOTE

This endpoint only processes the fields above; other image parameters (response_format, quality, user, etc.) are ignored. The image URL is given by the artifacts endpoint under Query & Download — response_format is not needed.

Text-to-Image

Pass only model + prompt (optionally size) for text-to-image.

Request Examples

cURL
Python
Node.js
curl https://api-model.shuntianchuang.cn/v1/tasks/vega \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-token" \
  -d '{
    "model": "wand-vega-image-lite",
    "prompt": "一只戴耳机的橘猫在写代码,扁平插画风格",
    "size": "1024x1024",
    "n": 1
  }'

Response Body

A successful submission returns the task object immediately, with status fixed at queued:

FieldTypeNotes
task_idstringTask ID, used for both polling and downloading
idstringSame as task_id
statusstringAlways queued right after submission
modelstringModel name used for this request
created_atintegerTask creation time (Unix seconds)

Response Example

{
  "created_at": 1791620512,
  "id": "task_c2eEf531tDsBj8t9hwcyFKlGu1tfZUXl",
  "model": "wand-vega-image-lite",
  "status": "queued",
  "task_id": "task_c2eEf531tDsBj8t9hwcyFKlGu1tfZUXl"
}

Image-to-Image

Same endpoint with input carrying reference images — the model redraws the whole image based on them (change style, change scene, keep the composition and subject, etc.).

input Fields

FieldTypeRequiredNotes
inputarray[object]YesMultimodal input array; each item's content is the list of reference images
input[].content[]array[object]YesEach reference image is written as {"type": "input_image", "image_url": "..."}
input[].content[].typestringYesAlways input_image
input[].content[].image_urlstringYesReference image location: public HTTP/HTTPS URL, or data:image/png;base64,... (Base64 for local images)

Reference Image Limits

ModelMax reference images
wand-vega-image-lite3
wand-vega-image-flash6
wand-vega-image-pro6 (extra billing from the 4th image on)

Request Examples

cURL
Python
Node.js
curl https://api-model.shuntianchuang.cn/v1/tasks/vega \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-token" \
  -d '{
    "model": "wand-vega-image-pro",
    "prompt": "保持原设计,加 3D 玻璃水晶质感,浮在蓝色渐变背景上",
    "size": "1024x1024",
    "n": 1,
    "input": [
      {
        "content": [
          { "type": "input_image", "image_url": "https://your-cdn/reference.png" }
        ]
      }
    ]
  }'

Notes

  • The prompt must include wording like "keep the original image / design" (保持原图 / 原设计), otherwise the model ignores the reference images and treats the task as plain text-to-image.
  • For local images or images you prefer not to expose, inline them as data:image/png;base64,... — see the WARNING below.
  • Max 10MB per reference image; PNG / JPEG supported.
  • Reference image resolution does not affect output size (determined by size).
WARNING

Reference images are downloaded by the upstream service, so they must be publicly reachable. In our tests an overseas image host (e.g. Wikimedia) failed to download and the task ended with 502001 上游模型服务异常或不可达 (upstream service error or unreachable). Use a publicly accessible URL, or inline the image as data:image/png;base64,... (recommended, most reliable).

Billing

Billing settles against the usage actually returned by the upstream: 0 pre-charged at submission, charged on completion at actual usage, and failed tasks are not billed. Consumption varies by model and reference image count — measured values (1024x1024, one reference image):

ModelText-to-imageImage-to-image (1 reference image)
wand-vega-image-lite13,500 tokens13,500 tokens
wand-vega-image-flash45,000 tokens45,000 tokens
wand-vega-image-pro95,000 tokens95,000 tokens

For wand-vega-image-pro image-to-image, the first 3 reference images are free and each image from the 4th on adds 10,000 tokens. Token prices and final amounts are subject to the Model Plaza; actual charges are visible in the console's "Usage Logs".

Errors

HTTPErrorNotes
401Invalid tokenToken invalid or missing — check the Authorization header
400model is requiredmodel missing from the body; the model name must come from the table above, otherwise the request cannot be routed to the channel
400model ... tiered expr run failedAppears when calling the Vega series through the synchronous POST /v1/images/generations endpoint (no longer supports Vega) — use the async API on this page instead
502502001 上游模型服务异常或不可达Transient upstream failure — just retry; for image-to-image, first check that the reference images are publicly reachable
502Artifact upstream authentication failedThe image URL has expired (the content_url signature is no longer valid) and the image is unretrievable — regenerate, or use your own re-hosted copy

For more error codes see Error Codes & Troubleshooting.

NOTE

The former synchronous endpoint POST /v1/images/generations no longer supports the Vega series — migrate to the async API on this page. The pre-upgrade synchronous integration is kept on the Legacy Guide for transition reference only.

After a successful submission, poll the task status and download the image — see Query & Download.