异步任务

了解如何使用异步模式处理耗时较长的 API 请求，通过任务 ID 查询进度和获取结果。

在 Playground 中体验

工作流程

异步模式适用于耗时较长的请求（如图片生成、视频生成），避免长时间等待 HTTP 连接超时。

1. 发起请求       2. 获取 task_id       3. 轮询状态         4. 获取结果
┌──────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────┐
│ POST ... │───→│ { id, status │───→│ GET /tasks/  │───→│ status = │
│ async:   │    │   "queued" } │    │   {taskId}   │    │"completed│
│ true     │    └──────────────┘    └──────────────┘    └──────────┘
└──────────┘                             ↑ 每 3-5 秒
                                         │ 重复查询

步骤说明

发起请求 — 在请求体中添加 "async": true
获取 task_id — API 返回任务 ID 和初始状态（queued）
轮询状态 — 定期调用查询接口，直到状态变为 completed 或 failed
获取结果 — 任务完成后，响应中包含生成结果（如图片 URL）

支持的模型

能力类型	典型耗时	默认模式	说明
图片生成	10-30 秒	异步	大部分图片模型默认使用异步模式
视频生成	1-5 分钟	异步	视频生成耗时较长，必须使用异步模式
文本生成	1-10 秒	同步	通常使用同步或流式模式，无需异步

INFO

具体的异步支持情况取决于模型的 syncMode 配置。在 Playground 中，可通过"异步模式"开关切换。

发起异步请求

在请求体中添加 "async": true 即可启用异步模式：

cURLPythonNode.js

bash

curl https://open.dieyuyun.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cat sitting on a windowsill",
    "size": "1024x1024",
    "async": true
  }'

python

import requests

response = requests.post(
    "https://open.dieyuyun.com/v1/images/generations",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-image-2",
        "prompt": "A cat sitting on a windowsill",
        "size": "1024x1024",
        "async": True,
    },
)
print(response.json())

javascript

const response = await fetch('https://open.dieyuyun.com/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2',
    prompt: 'A cat sitting on a windowsill',
    size: '1024x1024',
    async: true,
  }),
})
const data = await response.json()
console.log(data)

异步响应格式

json

{
  "id": "task_abc123xyz",
  "status": "queued",
  "progress": 0,
  "created_at": "2026-06-05T10:30:00Z",
  "request_id": "req_def456"
}

字段	类型	说明
id	string	任务唯一标识，用于后续查询
status	string	当前状态：`queued` / `processing`
progress	int	进度百分比（0-100）
created_at	string	任务创建时间
request_id	string	请求唯一标识

查询任务状态

接口信息

项目	值
方法	GET
路径	`/v1/tasks/{taskId}`
认证	Bearer Token

cURLPythonNode.js

bash

curl https://open.dieyuyun.com/v1/tasks/task_abc123xyz \
  -H "Authorization: Bearer YOUR_API_KEY"

python

import requests

response = requests.get(
    "https://open.dieyuyun.com/v1/tasks/task_abc123xyz",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
task = response.json()
print(f"Status: {task['status']}, Progress: {task['progress']}%")

javascript

const response = await fetch('https://open.dieyuyun.com/v1/tasks/task_abc123xyz', {
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
})
const task = await response.json()
console.log(`Status: ${task.status}, Progress: ${task.progress}%`)

响应格式

任务进行中：

json

{
  "id": "task_abc123xyz",
  "status": "processing",
  "progress": 60,
  "model_code": "gpt-image-2",
  "created_at": "2026-06-05T10:30:00Z",
  "updated_at": "2026-06-05T10:30:15Z"
}

任务完成：

json

{
  "id": "task_abc123xyz",
  "status": "completed",
  "progress": 100,
  "model_code": "gpt-image-2",
  "result": {
    "created": 1749116400,
    "data": [
      {
        "url": "https://cdn.dieyuyun.com/images/xxx.png",
        "revised_prompt": "A fluffy orange cat sitting on a sunlit windowsill..."
      }
    ]
  },
  "usage": {
    "input_tokens": 0,
    "output_tokens": 1
  },
  "created_at": "2026-06-05T10:30:00Z",
  "completed_at": "2026-06-05T10:30:25Z"
}

任务失败：

json

{
  "id": "task_abc123xyz",
  "status": "failed",
  "error_code": "upstream_error",
  "error_message": "The upstream provider returned an error",
  "created_at": "2026-06-05T10:30:00Z",
  "failed_at": "2026-06-05T10:30:10Z"
}

取消任务

接口信息

项目	值
方法	POST
路径	`/v1/tasks/{taskId}/cancel`
认证	Bearer Token

cURLPythonNode.js

bash

curl -X POST https://open.dieyuyun.com/v1/tasks/task_abc123xyz/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

python

import requests

response = requests.post(
    "https://open.dieyuyun.com/v1/tasks/task_abc123xyz/cancel",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())

javascript

const response = await fetch('https://open.dieyuyun.com/v1/tasks/task_abc123xyz/cancel', {
  method: 'POST',
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
})
console.log(await response.json())

WARNING

取消任务仅在任务处于 queued 或 processing 状态时有效。已完成或已失败的任务无法取消。

任务状态说明

状态	说明	是否终态
`queued`	任务已提交，等待处理	否
`processing`	任务正在处理中	否
`completed`	任务已完成，结果可获取	是
`failed`	任务失败，请查看错误信息	是
`cancelled`	任务已被取消	是
`expired`	任务已过期（结果已清理）	是

完整轮询示例

以下 Python 示例展示了完整的异步任务轮询流程：

python

import time
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://open.dieyuyun.com"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

# 1. 发起异步请求
response = requests.post(
    f"{BASE_URL}/v1/images/generations",
    headers=HEADERS,
    json={
        "model": "gpt-image-2",
        "prompt": "A beautiful sunset over the ocean",
        "size": "1024x1024",
        "async": True,
    },
)
task = response.json()
task_id = task["id"]
print(f"Task submitted: {task_id}")

# 2. 轮询任务状态
while True:
    status_resp = requests.get(
        f"{BASE_URL}/v1/tasks/{task_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
    )
    task = status_resp.json()
    status = task["status"]
    progress = task.get("progress", 0)

    print(f"Status: {status}, Progress: {progress}%")

    if status == "completed":
        print(f"Result: {task['result']}")
        break
    elif status in ("failed", "cancelled", "expired"):
        print(f"Task ended with status: {status}")
        if "error_message" in task:
            print(f"Error: {task['error_message']}")
        break

    time.sleep(3)  # 每 3 秒查询一次

最佳实践

合理的轮询间隔 — 建议每 3-5 秒查询一次，过于频繁的查询会增加不必要的负载
设置超时上限 — 为轮询设置最大等待时间（如 5 分钟），超时后进行告警或重试
处理终态 — 确保对 failed、cancelled、expired 等终态有适当的处理逻辑
使用指数退避 — 如果连续多次查询状态未变化，可适当增大查询间隔
保存 task_id — 将 task_id 持久化，以便在服务重启后仍可查询任务结果
及时获取结果 — 任务结果有过期时间，完成后应尽快下载或转存

另请参阅

错误码 — API 错误码完整参考
速率限制 — 了解 API 调用频率限制
API 参考 — API 通用说明

异步任务 ​

工作流程 ​

步骤说明 ​

支持的模型 ​

发起异步请求 ​

异步响应格式 ​

查询任务状态 ​

接口信息 ​

响应格式 ​

取消任务 ​

接口信息 ​

任务状态说明 ​

完整轮询示例 ​

最佳实践 ​

另请参阅 ​

异步任务

工作流程

步骤说明

支持的模型

发起异步请求

异步响应格式

查询任务状态

接口信息

响应格式

取消任务

接口信息

任务状态说明

完整轮询示例

最佳实践

另请参阅