异步调用 API 参考

本文介绍如何通过 OpenAI 兼容模式的 Responses API 异步调用阿里云百炼应用（智能体应用、工作流应用）。对于耗时较长的任务，只需在请求中设置 background 为 true，API 便会立即返回一个任务 ID，用于后续的查询与管理。这种"先提交、后查询"的方式，可有效避免请求超时或长时间等待。

异步任务暂不支持流式输出（stream=true）。

相关参考

同步调用：对于需要即时获取结果的实时交互场景，请参阅同步调用 API 参考。
DashScope API：如需获取更多功能，请参阅 DashScope API。

前提条件

已获取 API Key 并配置到环境变量。如果通过 OpenAI SDK 进行调用，还需要安装 OpenAI SDK。
已创建阿里云百炼应用并获取应用 ID。

接入地址

SDK base_url: https://dashscope.aliyuncs.com/api/v2/apps/agent/{APP_ID}/compatible-mode/v1/
HTTP Endpoint: POST https://dashscope.aliyuncs.com/api/v2/apps/agent/{APP_ID}/compatible-mode/v1/responses

请将 {APP_ID} 替换为实际的应用 ID。

创建异步任务

在请求中将 background 设为 true 即可创建异步任务：

from openai import OpenAI
import os

api_key = os.getenv("DASHSCOPE_API_KEY")
app_id = 'APP_ID'  # 替换为实际的应用 ID
base_url = f'https://dashscope.aliyuncs.com/api/v2/apps/agent/{app_id}/compatible-mode/v1/'

client = OpenAI(
    api_key=api_key,
    base_url=base_url
)

response = client.responses.create(
    input="请帮我生成一份详细的项目报告",
    background=True
)

print(f"任务 ID: {response.id}")
print(f"任务状态: {response.status}")

查询任务状态

通过任务 ID 查询异步任务的执行状态和结果：

# 查询任务状态
result = client.responses.retrieve(response.id)
print(f"状态: {result.status}")
if result.status == "completed":
    print(f"结果: {result.output}")

取消任务

对于尚未完成的异步任务，可以进行取消操作：

client.responses.cancel(response.id)

请求参数

参数	类型	必选	说明
input	string/array	是	用户输入内容。
background	boolean	是	设为 `true` 以创建异步任务。
model	string	否	模型名称。
previous_response_id	string	否	上一次响应的 ID，用于多轮对话。

响应对象

参数	类型	说明
id	string	任务唯一标识。
status	string	任务状态：`queued`、`in_progress`、`completed`、`failed`、`cancelled`。
output	array	任务完成后的输出消息列表。
usage	object	Token 使用信息（仅在完成后返回）。

错误码

如果调用失败并返回报错信息，请参阅错误码文档进行解决。

​前提条件

​接入地址

​创建异步任务

​查询任务状态

​取消任务

​请求参数

​响应对象

​错误码

前提条件

接入地址

创建异步任务

查询任务状态

取消任务

请求参数

响应对象

错误码