异步任务（图像 / 视频 / 文本）

适用于 图像生成、视频生成、长文本异步处理 等场景。提交任务后轮询状态，或配置 Webhook 接收完成通知。

注意：HTTP 入口当前使用 videoParams / imageParams / textParams 结构（非旧版扁平 prompt + params 格式）。

---

端点一览

Base URL：https://aiservice.jellytoken.com

---

两种接入方式

两种方式都经过 JELLYTOKEN 鉴权和计费，区别在于平台是否帮你翻译参数。详见 供应商原生接口兼容。

---

提交任务

请求

POST /api/ai/tasks
Authorization: Bearer uas_xxx
Content-Type: application/json

必须提供以下三者之一：videoParams、imageParams、textParams。

视频任务示例

{
  "modelKey": "wan2.6-i2v",
  "callbackId": "my-video-001",
  "callbackUrl": "https://your-server.com/webhook/jellytoken",
  "requestContext": {
    "user_id": "user-123"
  },
  "videoParams": {
    "prompt": "一只猫在草地上奔跑，电影感",
    "firstFrame": "https://example.com/start.jpg",
    "duration": 5,
    "resolution": "720p",
    "aspectRatio": "16:9",
    "extraParamsJson": "{\"generate_audio\":true}"
  }
}

图像任务示例

{
  "modelKey": "qwen-image-plus",
  "callbackId": "my-image-001",
  "imageParams": {
    "prompt": "赛博朋克风格城市夜景",
    "resolution": "2k",
    "aspectRatio": "1:1"
  }
}

文本任务示例

{
  "modelKey": "qwen-plus",
  "callbackId": "my-text-001",
  "textParams": {
    "messages": [
      {"role": "user", "content": "总结以下要点：..."}
    ],
    "temperature": 0.7,
    "maxTokens": 2048
  }
}

字段说明

平台字段处理说明

平台异步任务 API 不是简单透传——提交后，平台会将 videoParams / imageParams / textParams 中的标准字段（如 resolution、aspectRatio、duration）映射为对应厂商的原生参数（如 parameters.ratio、parameters.size），并可能施加默认值或范围约束。

• extraParamsJson 必须是合法 JSON 对象字符串，非法 JSON 会被拒绝。
• 平台仅映射各系列文档中 [平台字段映射] 表格列出的键；未列出的 extraParamsJson 键可能被忽略或按模型不同有差异。
• 如需完全控制厂商请求体，请使用 供应商原生接口兼容。

各模型具体映射与支持的扩展键见 模型接入说明 中对应系列文档。

---

提交响应

{
  "taskId": "12345__my-video-001",
  "status": "queued",
  "resultUrl": null,
  "error": null,
  "errorCode": null,
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

---

查询任务

GET /api/ai/tasks/12345__my-video-001
Authorization: Bearer uas_xxx

{
  "taskId": "12345__my-video-001",
  "status": "completed",
  "progress": 100,
  "resultUrl": "https://cdn.example.com/result/xxx.mp4",
  "resultUrlPublic": "https://cdn.example.com/result/xxx.mp4",
  "resultContent": null,
  "error": null,
  "errorCode": null,
  "notFound": false,
  "usage": {
    "promptTokens": 0,
    "completionTokens": 0,
    "totalTokens": 0
  },
  "externalDataJson": "{}"
}

status 取值

查单接口（GET /api/ai/tasks/{taskId}）返回以下状态（与提交响应的 queued 不同）：

执行中示例：

{
  "taskId": "12345__my-video-001",
  "status": "running",
  "progress": 51,
  "notFound": false
}

• 视频/图像：优先使用 resultUrlPublic（预签名 URL）
• 文本任务：结果可能在 resultContent

---

取消任务

POST /api/ai/tasks/{taskId}/cancel
Authorization: Bearer uas_xxx

取消成功时，reason 因任务所处阶段不同而略有差异：

尚未开始执行（查单 status 为 pending）：

{
  "success": true,
  "reason": "cancelled"
}

已在执行（查单 status 为 running）：

{
  "success": true,
  "reason": "cancel_flag_set"
}

两种情况下 success 均为 true，表示取消请求已受理。执行中取消时，请继续轮询查单，直至 status 变为 cancelled。

reason 取值

---

推荐集成模式

轮询

POST /api/ai/tasks → 获得 taskId，记录响应头 x-request-id
loop:
  GET /api/ai/tasks/{taskId}
    Header: x-request-id: （与 submit 相同，可选）
  if status in (completed, failed, cancelled): break
  # 进行中为 running，排队为 pending
  sleep 2~5s

• 查单用 taskId；联系平台排查用 submit 时的 x-request-id（详见 鉴权 · 请求追踪）
• poll / cancel 响应头会回显本次请求的 x-request-id

Webhook（推荐生产）

配置 callbackUrl，详见 Webhook 回调。

---

cURL 完整示例

以下示例只需要替换 API_KEY；若你要测试其他模型，把 modelKey 换成控制台复制的模型 ID。

export API_KEY="uas_你的密钥"
export API_BASE_URL="https://aiservice.jellytoken.com"

# 可选：自定义请求 ID，便于排查
TRACE_ID="demo-trace-$(date +%s)"

# 提交任务
TASK=$(curl -s -X POST "$API_BASE_URL/api/ai/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-request-id: $TRACE_ID" \
  -d '{
    "modelKey": "qwen-image-plus",
    "callbackId": "demo-001",
    "imageParams": {
      "prompt": "一只可爱的机器人，干净背景，产品渲染风格",
      "aspectRatio": "1:1",
      "resolution": "2k"
    }
  }')
echo "$TASK"

# 轮询一次；建议每 2~5 秒轮询，或使用 Webhook
TASK_ID=$(echo "$TASK" | jq -r .taskId)
curl -s -D - "$API_BASE_URL/api/ai/tasks/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-request-id: $TRACE_ID" | jq .

本示例依赖 jq 解析 taskId。如果没有安装 jq，也可以先从提交响应中手动复制 taskId，再调用查询接口。

---

相关文档

• 模型列表与元信息
• Webhook
• 错误码