阿里云百炼调用手册

使用兼容接口完成文本问答

通过标准 HTTP messages 数组调用千问,并读取生成文本和 Token 用量。

官方资料核对 2026-10-15示例代码,未进行真实接口实测
← 返回平台功能

接入准备

  • 北京地域百炼通用 Key,归属空间已授权 qwen-plus;账户有可用额度或付费条件。

准备环境变量

示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行;密钥不应放进公开网页。

DASHSCOPE_API_KEY
百炼通用模型 API Key;不要误用 Token Plan 专属 Key。
DASHSCOPE_WORKSPACE_ID
来自百炼控制台业务空间详情;虚构值,需替换为北京地域真实空间 ID。
终端
export DASHSCOPE_API_KEY='replace_with_bailian_api_key'
export DASHSCOPE_WORKSPACE_ID='example-workspace-id'

以上 export 适用于 macOS / Linux 的终端,在同一终端内运行后续代码。Python 示例保存为 request.py 后执行 python3 request.py。

调用步骤

  1. 01

    登录阿里云百炼控制台,按提示完成实名认证并同意服务协议;本例限定华北2(北京)地域。

  2. 02

    在 API Key 管理创建通用 API Key,选择归属业务空间;若用 RAM 用户,确认它有空间和模型权限,若选自定义权限,将目标模型纳入允许范围。

  3. 03

    在业务空间详情取得空间 ID,设置 DASHSCOPE_WORKSPACE_ID;将该空间、该地域的 Key 放入 DASHSCOPE_API_KEY。

  4. 04

    本例使用官方推荐的空间专属域名。旧北京 dashscope.aliyuncs.com 域名目前仍可使用;其他地域不能仅更换 Key 而保留北京接入域名。

  5. 05

    执行前在模型广场核对示例 model 对当前空间已授权,检查额度及用完即停设置;本页代码只在自己的服务端运行。

调用 01

创建非流式对话

本例使用 qwen-plus 和非思考、非流式模式;HTTP 中 enable_thinking 直接放在顶层,不包 extra_body。

POSThttps://${DASHSCOPE_WORKSPACE_ID}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions

请求头

Authorization
Bearer ${DASHSCOPE_API_KEY}
Content-Type
application/json

参数说明

参数表可左右滑动,查看完整说明。

字段 / 位置类型 / 必填说明
model请求体string必填本例 qwen-plus;模型别名可随服务升级变化,生产需要稳定行为时另选已核实的快照。
messages请求体array必填按顺序传 system/user/assistant 消息;本例为普通文字。
messages[].role / content请求体string必填消息角色和正文;多轮对话需要应用自己按协议保留上下文。
stream请求体boolean可选本例 false,返回完整 JSON;true 需改用流式读取。
enable_thinking请求体boolean可选本例 false;属于百炼扩展,不能套用到所有模型。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误,业务状态还需按下方返回示例核对。

cURL
cat > request-body.json <<'JSON'
{
  "model": "qwen-plus",
  "messages": [
    {
      "role": "system",
      "content": "简洁回答用户问题。"
    },
    {
      "role": "user",
      "content": "用一句话说明 API 文本模型能做什么。"
    }
  ],
  "stream": false,
  "enable_thinking": false
}
JSON

# 执行后核对返回 JSON 的业务状态;HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://${DASHSCOPE_WORKSPACE_ID}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions" \
  --header "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
  --header "Content-Type: application/json" \
  --data-binary @request-body.json
Python 3
import json
import os
import re
import urllib.request
import urllib.error

def expand(value):
    return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
                  lambda match: os.environ[match.group(1)], value)

url = expand("https://${DASHSCOPE_WORKSPACE_ID}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions")
headers = {
    "Authorization": expand("Bearer ${DASHSCOPE_API_KEY}"),
    "Content-Type": expand("application/json"),
}
body = {
    "model": "qwen-plus",
    "messages": [
        {
            "role": "system",
            "content": "简洁回答用户问题。",
        },
        {
            "role": "user",
            "content": "用一句话说明 API 文本模型能做什么。",
        },
    ],
    "stream": False,
    "enable_thinking": False,
}
data = json.dumps(body, ensure_ascii=False).encode("utf-8")
request = urllib.request.Request(url, data=data, headers=headers, method="POST")
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))
Node.js
// Node.js 22+,保存为 request.mjs 后运行 node request.mjs
function expand(value) {
  return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
    if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
    return process.env[name];
  });
}

const url = expand("https://${DASHSCOPE_WORKSPACE_ID}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions");
const headers = Object.fromEntries(
  Object.entries({
  "Authorization": "Bearer ${DASHSCOPE_API_KEY}",
  "Content-Type": "application/json"
}).map(([key, value]) => [key, expand(value)])
);
const body = {
  "model": "qwen-plus",
  "messages": [
    {
      "role": "system",
      "content": "简洁回答用户问题。"
    },
    {
      "role": "user",
      "content": "用一句话说明 API 文本模型能做什么。"
    }
  ],
  "stream": false,
  "enable_thinking": false
};
const response = await fetch(url, {
  method: "POST",
  headers,
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));

返回示例

按官方字段整理的响应结构示意,ID、文本和数字均为虚构,非接口实测结果。取 choices[].message.content,检查 finish_reason;usage 为计量字段,不等于字符数。 以下为结构示意,非本站实测结果。

JSON
{
  "id": "chatcmpl-example-not-real",
  "object": "chat.completion",
  "model": "qwen-plus",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "可以用于生成摘要、回答问题和处理文本。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 16,
    "total_tokens": 40
  }
}

常见错误与排查

HTTP 401 InvalidApiKey / invalid_api_keyKey 错误或 Key 与接入地址不匹配。
检查环境变量、所属空间/地域;不要混用 Token Plan 专属 Key 和通用 Base URL。
HTTP 403 Model.AccessDenied业务空间无权调用目标模型。
核对空间授权、自定义 Key 模型范围及模型是否需要申请;模型名存在不代表账号已获准使用。
HTTP 429 Throttling.RateQuota调用次数达到 RPS/RPM 上限。
降低并发、平滑调度并退避;不要无限重试。
HTTP 429 Throttling.AllocationQuota / insufficient_quotaToken 用量达到 TPS/TPM 等分配上限。
缩短输入、降低并发,查看该模型的额度;与账户欠费和 Token Plan 次数限制分别排查。

调用注意

  • 返回 finish_reason=length 表示达到长度限制;content_filter 等结束原因要单独处理,不当作完整成功答案。
  • max_tokens 已被文档标注即将废弃;max_completion_tokens 的支持范围按模型核对,本例不假设所有旧型号都接受该参数。
  • 兼容协议不代表兼容所有 OpenAI 参数。流式 SSE、工具调用、JSON Schema 需要各自支持条件,不能只更换 Base URL 就承诺全部功能可用。

注意事项

  • 文本调用按具体模型、地域、输入长度档位和输入/输出 Token 计费;qwen-plus 不同档位不能概括成一个固定单价。
  • 新人额度有模型范围及有效期,开启用完即停可按其规则停用;不承诺永久免费。

核验来源

本站按官方资料整理本场景的必要调用步骤与代码,覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。

  1. 01
  2. 02
    首次调用与开通条件核验日期 2026-10-15
  3. 03
  4. 04
  5. 05
  6. 06
    百炼 HTTP/业务错误码核验日期 2026-10-15

阿里云百炼的其他调用手册

← 返回阿里云百炼的全部功能