# 阿里云百炼 — 应用调用 DashScope API 参考

> 来源：[应用调用-DashScope API](https://bailian.console.aliyun.com/cn-beijing/?tab=api#/api/?type=app&url=2846133)
> 采集日期：2026-02-28

---

本文介绍 DashScope API 调用阿里云百炼应用（智能体、工作流）的输入与输出参数。

## 1. 调用方式

- HTTP 接口调用
  - 请求地址：`POST https://dashscope.aliyuncs.com/api/v1/apps/{APP_ID}/completion`
  - 其中 `APP_ID` 需替换为您的实际应用 ID。
- SDK 调用
  - Python/Java SDK：已默认配置正确的 endpoint
  - 自定义 endpoint：可通过 `base_url` 参数配置

## 2. 前置准备

1. 创建应用：前往 [应用管理](https://bailian.console.aliyun.com/?tab=app#/app-center) 创建百炼应用并获取应用 ID。
2. 获取 API Key：通过 [密钥管理](https://bailian.console.aliyun.com/?tab=app#/api-key) 获取，并 [配置 API Key 到环境变量](https://help.aliyun.com/zh/model-studio/configure-api-key-through-environment-variables)。
3. 安装 SDK（可选）：若使用 SDK 调用，请安装相应语言的 [DashScope SDK](https://help.aliyun.com/zh/model-studio/install-sdk)。

## 3. 请求示例（Python 单轮对话）

```python
import os
from http import HTTPStatus
from dashscope import Application

response = Application.call(
    # 若没有配置环境变量，可用百炼API Key将下行替换为：api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    app_id='APP_ID',       # 替换为实际的应用 ID
    prompt='你是谁？'
)

if response.status_code != HTTPStatus.OK:
    print(f'request_id={response.request_id}')
    print(f'code={response.status_code}')
    print(f'message={response.message}')
    print(f'请参考文档：https://help.aliyun.com/zh/model-studio/developer-reference/error-code')
else:
    print(response.output.text)
```

## 4. 请求体参数（完整）

### 必选参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `app_id` | string | 应用标识。可在应用管理页面的应用卡片上获取。Java SDK 中为 `appId`。通过 HTTP 调用时，将实际应用 ID 放入 URL 中替换 `APP_ID`。 |
| `prompt` | string | 用户的输入指令，用于指导应用生成回复。通过 HTTP 调用时，请将 prompt 放入 `input` 对象中。 |

### 可选参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `session_id` | string | — | 历史对话标识。传入后请求将自动携带云端存储的对话历史。此时必须传递 `prompt`。该 ID 在连续 1 小时内无任何请求后自动失效。 |
| `messages` | array | — | 传递给大模型的上下文，按对话顺序排列。使用 `messages` 时无需传递 `prompt` 和 `session_id`。若同时传入 `session_id` 和 `messages`，则优先使用 `messages`。 |
| `workspace` | string | — | 业务空间标识。仅调用子业务空间的应用时需传递。HTTP 调用时指定 Header 中的 `X-DashScope-WorkSpace`。 |
| `stream` | boolean | `false` | 是否以流式输出方式回复。推荐设置为 `true`，可提升阅读体验并降低超时风险。HTTP 实现流式输出请在 Header 中指定 `X-DashScope-SSE` 为 `enable`。 |
| `incremental_output` | boolean | `false` | 流式输出模式下是否开启增量输出。推荐设置为 `true`。`false`：每次输出当前已生成的整个序列；`true`：增量输出，后续内容不包含已输出内容。 |
| `has_thoughts` | boolean | `false` | 是否输出插件调用、知识检索的过程，或已开启思考模式的模型思考过程，在 `thoughts` 字段中查看。 |
| `model_id` | string | — | 模型名称（仅智能体应用支持）。API 传递的 `model_id` 与控制台配置不同时，以 API 参数值为准。 |
| `memory_id` | string | — | 长期记忆体 ID（仅智能体应用支持）。通过 [CreateMemory](https://help.aliyun.com/zh/model-studio/api-bailian-2023-12-29-creatememory) 创建。 |
| `dialog_round` | integer | — | 携带的上下文轮数（仅智能体应用支持）。轮数越多，对话相关性越强。API 参数优先于控制台配置。 |
| `enable_thinking` | boolean | `false` | 在深度思考模型中切换思考/非思考模式。`true` 时模型先输出思考过程再返回最终答案。要获取思考内容，须同时将 `has_thoughts` 设为 `true`。 |
| `enable_system_time` | boolean | `true` | 控制模型是否自动获取当前时间（北京时间）（仅智能体应用支持）。设为 `false` 时需通过自定义变量手动传入时间。 |
| `enable_web_search` | boolean | `false` | 模型生成回复时是否使用互联网搜索结果（仅智能体应用支持）。若调用时未设置，以应用内联网搜索开关状态为准。 |
| `image_list` | array | — | 图片列表。支持图像 URL 和 Data URL（Base64 编码）。应用内需选择视觉理解模型。 |
| `file_list` | array | — | 包含一个或多个文件 URL 的列表（仅智能体应用支持）。 |

### messages 消息类型

| 消息类型 | 说明 |
|---------|------|
| System Message (`object`, 可选) | 系统消息，用于设定大模型的角色、语气、任务目标或约束条件等。一般放在 `messages` 数组的第一位。 |
| User Message (`object`, 必选) | 用户消息，用于向模型传递问题、指令或上下文等。 |
| Assistant Message (`object`, 可选) | 模型的回复。通常用于在多轮对话中作为上下文回传给模型。 |

### biz_params 参数传递

`biz_params` 用于应用通过自定义变量、节点或插件传递参数。

- 工作流应用开始节点的自定义变量直接传递：
  ```python
  biz_params = {"city": "杭州"}
  ```
- 智能体应用通过以下字段传递：
  - `user_prompt_params` (object, 可选)：自定义提示词变量参数。一个应用内变量名不可重复，上限 10 个。
    ```python
    biz_params = {
        "user_prompt_params": {
            "date": "2025年03月03日",
            "city": "杭州"
        }
    }
    ```
  - `user_defined_params` (object, 可选)：自定义插件参数。每个键为插件的 `TOOL_ID`，值为该插件所需的参数对象。
  - `user_defined_tokens` (object, 可选)：自定义插件的用户级鉴权信息。

### rag_options 知识库检索参数（仅智能体应用）

| 参数 | 类型 | 说明 |
|------|------|------|
| `pipeline_ids` | array (必选) | 包含一个或多个知识库 ID 的列表，上限 5 个。 |
| `file_ids` | array (可选) | 包含一个或多个非结构化文档 ID 的列表，上限 5 个。须同时传入文档所属的知识库 ID。 |
| `metadata_filter` | object (可选) | 非结构化文档的元数据，检索具备该元数据的文档。 |
| `tags` | array (可选) | 包含一个或多个非结构化文档标签的列表。 |
| `structured_filter` | object (可选) | 结构化文档的列名和值，键值对形式。 |
| `session_file_ids` | array (可选) | 包含一个或多个文件 ID 的列表，上限 10 个。文件 ID 必须以 `file_session_` 开头且状态为 `FILE_IS_READY`。 |

### flow_stream_mode 工作流流式输出模式

| 值 | 说明 |
|----|------|
| `message_format` (推荐) | 在 `message` 字段输出指定节点（流程输出节点或结束节点）的结果。需在控制台开启目标节点的流式输出开关。 |
| `full_thoughts` (默认) | 在 `thoughts` 字段输出所有节点的结果。使用此模式时须同时将 `has_thoughts` 设为 `true`。 |
| `agent_format` | 在 `text` 字段输出指定节点（大模型节点或结束节点）的结果。请勿在并行节点上使用此模式。 |

## 5. 响应对象

### 响应示例（单轮对话）

```json
{
  "output": {
    "finish_reason": "stop",
    "session_id": "6105c965c31b40958a43dc93c28c7a59",
    "text": "我是通义千问，由阿里云开发的AI助手。我被设计用来回答各种问题、提供信息和与用户进行对话。有什么我可以帮助你的吗？"
  },
  "usage": {
    "models": [
      {
        "output_tokens": 36,
        "model_id": "qwen-plus",
        "input_tokens": 74
      }
    ]
  },
  "request_id": "f97ee37d-0f9c-9b93-b6bf-bd263a232bf9"
}
```

### 响应示例（知识库检索，含引用来源）

> 需在百炼控制台的智能体应用内，单击检索配置，打开"展示回答来源"开关并发布应用。

```json
{
  "text": "根据您的预算，我推荐您考虑百炼 Zephyr Z9...<ref>[1]</ref>。",
  "finish_reason": "stop",
  "session_id": "6c1d47fa5eca46b2ad0668c04ccfbf13",
  "thoughts": null,
  "doc_references": [
    {
      "index_id": "1",
      "title": "百炼手机产品介绍",
      "doc_id": "file_7c0e9abee4f142f386e488c9baa9cf38_10317360",
      "doc_name": "百炼系列手机产品介绍",
      "doc_url": null,
      "text": "【文档名】:百炼系列手机产品介绍\n【标题】:百炼手机产品介绍\n【正文】:...",
      "biz_id": null,
      "images": [],
      "page_number": [0]
    }
  ]
}
```

### 异常响应示例

```
request_id=1d14958f-0498-91a3-9e15-be477971967b, code=401, message=Invalid API-key provided.
```

### 响应参数说明

| 参数 | 类型 | 说明 |
|------|------|------|
| `status_code` | string | 返回的状态码。`200` 表示请求成功，否则表示请求失败。Java SDK 不返回该参数，调用失败会抛出异常。 |
| `request_id` | string | 本次调用的唯一标识符。 |
| `code` | string | 错误码，调用成功时为空值（仅 Python SDK 返回）。 |
| `message` | string | 错误详细信息，请求成功则忽略（仅 Python SDK 返回）。 |

### output 对象

| 字段 | 类型 | 说明 |
|------|------|------|
| `text` | string | 模型生成的回复内容。 |
| `finish_reason` | string | 完成原因。`stop` 为自然结束，`null` 为强制中断（如达到最大长度限制或手动停止）。 |
| `session_id` | string | 当前对话的唯一标识。在后续请求中传入，可携带历史对话记录。 |
| `thoughts` | array | 将 `has_thoughts` 设为 `true` 时，可查看插件调用、知识检索的过程，或深度思考模型的思考过程。 |
| `doc_references` | array | 检索的召回文档中被模型引用的文档信息。需在控制台打开"展示回答来源"开关。 |
| `workflow_message` | object | 包含工作流节点状态和消息的对象（工作流应用）。 |

### usage 对象

| 字段 | 类型 | 说明 |
|------|------|------|
| `models` | array | 本次调用的模型信息。 |
| `models[].model_id` | string | 模型名称。 |
| `models[].input_tokens` | integer | 输入 Token 数量。 |
| `models[].output_tokens` | integer | 输出 Token 数量。 |

## 6. HTTP 请求结构

通过 HTTP 直接调用时，请求体结构如下：

```json
{
  "input": {
    "prompt": "你是谁？",
    "session_id": "可选",
    "messages": [],
    "biz_params": {},
    "image_list": [],
    "file_list": [],
    "memory_id": "可选"
  },
  "parameters": {
    "has_thoughts": false,
    "incremental_output": false,
    "rag_options": {},
    "flow_stream_mode": "full_thoughts",
    "model_id": "可选",
    "dialog_round": 3,
    "enable_thinking": false,
    "enable_system_time": true,
    "enable_web_search": false
  }
}
```

HTTP Header：
- `Authorization`: `Bearer {DASHSCOPE_API_KEY}`
- `Content-Type`: `application/json`
- `X-DashScope-SSE`: `enable`（流式输出时）
- `X-DashScope-WorkSpace`: `{workspace_id}`（子业务空间时）

## 7. 错误码

如果调用失败并返回报错信息，请参阅 [错误信息](https://help.aliyun.com/zh/model-studio/error-code) 进行解决。

## 8. 获取 APP ID 和 Workspace ID

- APP ID：访问 [应用管理](https://bailian.console.aliyun.com/#/app-center) 界面，在应用列表中找到目标应用，复制应用的 APP ID。
- Workspace ID：业务空间的唯一标识。仅在调用子业务空间下的应用时，API 请求中才必须包含 Workspace ID。
  - 获取当前业务空间 ID：前往百炼控制台首页，单击左下角设置图标 → 业务空间详情。
  - 查询所有业务空间 ID：需超级管理员权限，前往业务空间管理界面查看。

## 9. SDK 版本要求

| 功能 | Python SDK 最低版本 | Java SDK 最低版本 |
|------|-------------------|------------------|
| messages 参数 | 1.20.14 | 2.17.0 |
| flow_stream_mode | 1.24.0 | 2.21.0 |
| file_list | 1.24.7 | 2.21.13 |
| session_file_ids | 1.20.14 | 2.17.0 |
| model_id | — | 2.19.3 |
| enable_thinking | — | 2.20.0 |
| enable_system_time | — | 2.19.3 |
| enable_web_search | — | 2.19.3 |
| dialog_round | — | 2.19.3 |