豆包大模型API调用教程：火山方舟Python快速入门

先说结论：豆包（火山方舟）可在国内网络环境中使用。本教程不会要求你注册境外模型账号；API Key请只保存在环境变量中，不要写进源码或上传到代码仓库。

一、开始前需要准备什么

1. 在豆包（火山方舟）官方开放平台注册并完成平台要求的认证。
2. 在控制台创建API Key，并确认账户具有模型调用额度。
3. 电脑安装Python 3.9或更高版本。

二、安装SDK并设置API Key

python -m pip install -U volcengine-python-sdk[ark]
# Windows PowerShell
$env:ARK_API_KEY="替换为控制台创建的API Key"

关闭当前终端后，临时环境变量通常会失效。长期使用时可在系统环境变量或部署平台的“密钥”设置中保存，但不要公开。

三、运行第一个Python请求

import os
from volcenginesdkarkruntime import Ark

client = Ark(
    api_key=os.environ["ARK_API_KEY"],
    base_url="https://ark.cn-beijing.volces.com/api/v3",
)

response = client.responses.create(
    model="doubao-seed-2-0-lite-260215",
    input="请用三句话解释什么是RAG。",
)
print(response.output_text)

当前基础地址为 https://ark.cn-beijing.volces.com/api/v3，示例模型为 doubao-seed-2-0-lite-260215。火山方舟模型更新较快，实际调用时请从控制台模型列表复制当前可用的模型或推理接入点标识。

四、把OpenAI教程迁移过来

如果原教程使用的是标准对话接口，通常只需修改三项：API Key环境变量、base_url和model。消息列表、流式输出等常用结构多数可以保留。

不能直接照搬的情况：Assistants、Realtime、托管文件搜索、特定图像或音频接口、厂商专属Agent SDK等高级能力并不一定兼容。遇到这些内容时，应保留教程的架构思路，按照目标平台官方接口重新实现。

五、常见错误排查

401或API Key错误

确认Key复制完整、环境变量名正确，并检查是否把其他平台的Key与当前基础地址混用。

模型不存在或无权限

从控制台复制当前可调用的模型标识；部分模型需要先开通服务或选择正确地域。

连接超时

先访问平台状态页，再检查服务器出口、防火墙、代理和请求超时。不要在失败时无限重试。

参数不兼容

先删除平台不支持的可选参数，用最小请求验证成功后再逐项恢复。

六、官方资料与其他国内方案

火山方舟官方快速入门 →