• 简体中文
  • 查询与下载(Vega 格式)

    查询 Vega 图片生成任务的进度与结果并下载图片,与提交任务配套使用。提交后用返回的 task_id 轮询,直到 status 变为 SUCCESS 或 FAILURE,建议每 2~3 秒一次。

    端点

    • 查询任务状态:GET /v1/tasks/{task_id}
    • 下载图片:GET /v1/tasks/{task_id}/artifacts

    认证

    请求头携带 Bearer 令牌:

    Authorization: Bearer sk-你的令牌

    路径参数

    参数类型必填说明
    task_idstring是提交接口返回的任务 ID

    查询任务状态

    GET /v1/tasks/{task_id}

    响应体

    字段类型说明
    task_idstring任务 ID
    platformstring固定为 vega
    statusstring任务状态,取值见下表
    progressstring进度,如 50%、100%
    fail_reasonstring失败原因,成功时为空
    created_atinteger创建时间(Unix 秒)
    finished_atinteger完成时间(Unix 秒),未完成时为 0

    状态取值:

    status含义
    QUEUED排队中
    IN_PROGRESS生成中
    SUCCESS生成成功
    FAILURE生成失败(不扣费,原因见 fail_reason)

    响应示例

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

    查询响应里不含图片。status 变为 SUCCESS 后,请再调下方下载图片接口取图。

    下载图片

    GET /v1/tasks/{task_id}/artifacts

    响应体

    字段类型说明
    task_idstring任务 ID
    artifacts[]array产物列表,Vega 每次生成一张图,只有一个元素
    artifacts[].keystring产物标识,如 image-1
    artifacts[].typestring固定为 image
    artifacts[].content_urlstring图片地址,免令牌,但有时效,请立即下载转存

    响应示例

    {
      "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 是临时地址:带签名、有时效,不要当长期图片链接分发或写入数据库。拿到后请立即下载转存到自己的存储,地址过期后再请求会返回 502(见提交任务的错误码)。

    图片内容也可以直接打内容端点获取,二者取到的是同一份内容:

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

    注意这条不带 ?access= 的地址需要带令牌(Authorization: Bearer sk-你的令牌);上一步 artifacts[].content_url 里已带 ?access=,那种形式才免令牌。

    轮询示例

    从提交到取图的完整流程(也可从第 2 步开始,换成你已有的 task_id):

    cURL
    Python
    Node.js
    # 1. 提交
    curl -s https://api-model.shuntianchuang.cn/v1/tasks/vega \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-你的令牌" \
      -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. 轮询(把 <task_id> 换成上一步的返回值,建议每 2~3 秒一次)
    curl -s https://api-model.shuntianchuang.cn/v1/tasks/<task_id> \
      -H "Authorization: Bearer sk-你的令牌"
    # status 为 SUCCESS 后,调下载接口取图
    
    # 3. 取图(content_url 免令牌但有时效,请立即下载转存)
    curl -s https://api-model.shuntianchuang.cn/v1/tasks/<task_id>/artifacts \
      -H "Authorization: Bearer sk-你的令牌"
    # => {"artifacts":[{"key":"image-1","type":"image","content_url":"https://..."}],"task_id":"task_xxxx"}
    
    curl -o output.png "<content_url>"

    计费按上游实际返回的用量结算(提交 0 预扣、失败不扣费),各模型实测消耗见提交任务页的计费。