Query & Download (Vega Format)

Query the progress and result of a Vega image generation task and download the image, used together with Submit Task. Poll with the returned task_id until status becomes SUCCESS or FAILURE, about once every 2–3 seconds.

Endpoint

  • Query task status: GET /v1/tasks/{task_id}
  • Download the image: GET /v1/tasks/{task_id}/artifacts

Authentication

Pass the Bearer token in the request header:

Authorization: Bearer sk-your-token

Path Parameters

ParameterTypeRequiredNotes
task_idstringYesTask ID returned by the submit endpoint

Query Task Status

GET /v1/tasks/{task_id}

Response Body

FieldTypeNotes
task_idstringTask ID
platformstringAlways vega
statusstringTask status; see the table below
progressstringProgress, e.g. 50%, 100%
fail_reasonstringFailure reason; empty on success
created_atintegerCreation time (Unix seconds)
finished_atintegerFinish time (Unix seconds); 0 while unfinished

Status values:

statusMeaning
QUEUEDQueued
IN_PROGRESSGenerating
SUCCESSGenerated successfully
FAILUREGeneration failed (not billed; see fail_reason)

Response Example

{
  "created_at": 1791620512,
  "fail_reason": "",
  "finished_at": 1791620531,
  "platform": "vega",
  "progress": "100%",
  "status": "SUCCESS",
  "task_id": "task_c2eEf531tDsBj8t9hwcyFKlGu1tfZUXl"
}
NOTE

The query response does not contain the image. Once status is SUCCESS, call the download endpoint below to fetch it.

Download the Image

GET /v1/tasks/{task_id}/artifacts

Response Body

FieldTypeNotes
task_idstringTask ID
artifacts[]arrayArtifact list — Vega generates one image per call, so a single element
artifacts[].keystringArtifact key, e.g. image-1
artifacts[].typestringAlways image
artifacts[].content_urlstringImage URL — no token needed but time-limited: download and re-host immediately

Response Example

{
  "artifacts": [
    {
      "key": "image-1",
      "type": "image",
      "content_url": "https://api-model.shuntianchuang.cn/v1/tasks/task_c2eEf531tDsBj8t9hwcyFKlGu1tfZUXl/artifacts/image-1/content?access=xxxxx"
    }
  ],
  "task_id": "task_c2eEf531tDsBj8t9hwcyFKlGu1tfZUXl"
}
WARNING

content_url is a temporary URL: signed and time-limited — do not distribute it as a long-term image link or write it into your database. Download and re-host it to your own storage immediately; once expired, further requests return 502 (see the error table on Submit Task).

The image content can also be fetched from the content endpoint; both return the same content:

GET /v1/tasks/{task_id}/artifacts/{key}/content

Note that the address without ?access= requires a token (Authorization: Bearer sk-your-token); only the artifacts[].content_url form that already carries ?access= is token-free.

Polling Examples

The complete flow from submission to download (you can also start at step 2 with a task_id you already have):

cURL
Python
Node.js
# 1. Submit
curl -s 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
  }'
# => {"created_at":...,"id":"task_xxxx","model":"wand-vega-image-lite","status":"queued","task_id":"task_xxxx"}

# 2. Poll (replace <task_id> with the value returned above, about every 2-3 seconds)
curl -s https://api-model.shuntianchuang.cn/v1/tasks/<task_id> \
  -H "Authorization: Bearer sk-your-token"
# Once status is SUCCESS, call the artifacts endpoint

# 3. Fetch the image (content_url needs no token but is time-limited — download immediately)
curl -s https://api-model.shuntianchuang.cn/v1/tasks/<task_id>/artifacts \
  -H "Authorization: Bearer sk-your-token"
# => {"artifacts":[{"key":"image-1","type":"image","content_url":"https://..."}],"task_id":"task_xxxx"}

curl -o output.png "<content_url>"

Billing settles against the usage actually returned by the upstream (0 pre-charged at submission; failed tasks are not billed) — measured consumption per model is on the Submit Task billing section.