模型与任务

先通过模型接口确认“可以调用什么”，再通过任务接口跟踪“耗时请求执行到了哪里”。

模型名称和任务状态都以当前账号的实际接口响应为准。示例中的名称只用于说明结构，不应直接作为生产配置。

查询可用模型


curl -X GET "${BASE_API_URI}/v1/models" \
  -H 'Authorization: Bearer <access-credential-secret>'

典型列表结构：


{
  "object": "list",
  "data": [
    {
      "id": "qwen-plus",
      "object": "model",
      "created": 0,
      "owned_by": "tian_suan"
    }
  ]
}

请求体中的 model 应使用 data[].id 的准确值。复制后保留原始大小写与标点，并通过一条最小请求验证账号确实可以调用。

选择模型时确认什么

问题	为什么重要	如何确认
当前账号是否可见	示例模型不代表所有账号都已开放	查询 `/v1/models` 或查看控制台
是否适合目标能力	文本、图片和其他任务需要匹配的模型	结合接口类型做真实请求
参数是否受支持	不同模型的可选参数可能不同	从最小参数开始逐项增加
用量是否符合预期	模型与输入规模会影响消耗	记录响应用量并在控制台核对

跟踪异步任务

查询任务列表


curl -X GET "${BASE_API_URI}/v1/tasks?limit=20" \
  -H 'Authorization: Bearer <access-credential-secret>'

列表适合按时间或状态寻找近期任务，但业务代码应优先保存创建请求返回的任务 ID，不要依赖反复扫描列表来定位。

查询单个任务


curl -X GET "${BASE_API_URI}/v1/tasks/<task_id>" \
  -H 'Authorization: Bearer <access-credential-secret>'

根据实际响应判断任务是否仍在执行、已经完成或已经失败。未进入终态时再按合理间隔继续查询。

按需取消


curl -X POST "${BASE_API_URI}/v1/tasks/<task_id>/cancel" \
  -H 'Authorization: Bearer <access-credential-secret>'

不同任务类型支持的取消行为可能不同。任务已经完成或失败时，取消请求可能不再产生效果。

按需删除


curl -X DELETE "${BASE_API_URI}/v1/tasks/<task_id>" \
  -H 'Authorization: Bearer <access-credential-secret>'

删除前确认业务已经保存所需结果与排障信息，并以接口实际返回判断操作是否成功。

列表查询参数

参数	作用	使用建议
`status`	按任务状态过滤	使用接口实际返回的状态值
`limit`	限制单次返回数量	从较小数量开始，避免一次读取过多记录

设计任务跟踪逻辑

环节	至少保存
创建后	任务 ID、业务记录 ID、模型、创建时间
轮询中	最近状态、查询时间、查询次数
完成后	完成时间、结果位置或摘要
失败后	错误信息、最后状态、请求 ID
取消或删除后	操作时间与接口返回

轮询必须有间隔、超时和停止条件。无限轮询既不能修复失败任务，也会制造额外请求和排障噪声。