火山方舟怎么调用大模型API

调用火山方舟大模型 API 的核心路径是：获取 API Key → 开通模型服务 → 安装 SDK 或直接使用 HTTP 请求 → 调用对应接口。火山方舟兼容 OpenAI 接口规范，如果你已有 OpenAI SDK 的使用经验，迁移成本很低。

🔑 第一步：获取并配置 API Key

API Key 是调用方舟平台的鉴权凭据，所有请求都需要携带[reference:0]。

1. 获取 API Key：登录火山方舟控制台，在左下角选择 API Key 管理，点击创建并复制保存[reference:1]。Key 的格式为 ark-<uuid>-<suffix> 或历史 UUID 格式[reference:2]。
2. 配置环境变量：推荐将 Key 配置到环境变量中，避免硬编码在代码里。不同系统的命令如下[reference:3]：
   • macOS / Linux：export ARK_API_KEY="your_api_key_here"
   • Windows CMD：setx ARK_API_KEY "your_api_key_here"
   • Windows PowerShell：$env:ARK_API_KEY = "your_api_key_here"

注意：API Key 是敏感信息，不要泄露给他人，也不要提交到公开的代码仓库[reference:4]。

📦 第二步：开通模型服务与安装 SDK

开通模型：新用户有免费额度，额度用完后需访问 开通管理页面 开通对应模型服务[reference:5]。部分模型（如 Seedance 2.0）需要账户余额超过 200 元或购买资源包才能开通[reference:6]。

安装 SDK：火山方舟提供官方 SDK 以及 OpenAI 兼容 SDK，根据你的开发语言选择[reference:7]。

• Python（版本 3.8+）：
  • 官方 SDK：python -m pip install --upgrade arkruntime
  • OpenAI 兼容 SDK：pip install openai
• Go（版本 1.20+）：go get github.com/volcengine/ark-runtime-go@latest
• Java（版本 1.8+）：在 pom.xml 中添加依赖 com.volcengine:ark-runtime，版本号从 Maven Central 获取最新稳定版
• Node.js：npm install @volcengine/ark-runtime

🚀 第三步：发起 API 请求

方舟提供两个核心接口：Responses API（推荐，格式更简洁，原生支持上下文管理）和 Chat API（兼容 OpenAI 格式，适合迁移现有代码）[reference:8]。

方式一：Responses API（推荐）

接口地址：POST https://ark.cn-beijing.volces.com/api/v3/responses[reference:9]

Python 示例：

import os
from volcenginesdkarkruntime import Ark
client = Ark(
base_url='https://ark.cn-beijing.volces.com/api/v3',
api_key=os.getenv('ARK_API_KEY'),
)
response = client.responses.create(
model="doubao-seed-2-1-pro-260628",
input="hello"
)
for item in response.output:
if item.type == "message":
for content in item.content:
if content.type == "output_text":
print(content.text)

cURL 示例：

curl https://ark.cn-beijing.volces.com/api/v3/responses \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seed-2-1-pro-260628",
"input": "hello"
}'

方式二：Chat API（OpenAI 兼容）

接口地址：POST https://ark.cn-beijing.volces.com/api/v3/chat/completions[reference:10]

Python（OpenAI SDK）示例：

import os
from openai import OpenAI
client = OpenAI(
base_url='https://ark.cn-beijing.volces.com/api/v3',
api_key=os.getenv('ARK_API_KEY'),
)
response = client.chat.completions.create(
model="doubao-seed-2-1-pro-260628",
messages=[
{"role": "user", "content": "常见的十字花科植物有哪些？"}
],
)
print(response.choices[0].message.content)

cURL 示例：

curl https://ark.cn-beijing.volces.com/api/v3/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ARK_API_KEY" \
-d '{
"model": "doubao-seed-2-1-pro-260628",
"messages": [
{"role": "user", "content": "常见的十字花科植物有哪些？"}
]
}'

⚡ 进阶功能

• 流式输出：在请求中设置 "stream": true，模型会持续发送已生成的数据片段，无需等待完整内容生成完毕，适合长文本输出场景[reference:11]。Python 中遍历 completion 对象即可逐块打印：for chunk in completion: print(chunk.choices[0].delta.content, end="")[reference:12]。
• 多模态输入：Chat API 的 messages 中支持传入图片、视频、音频等多模态内容。图片可通过 file_id 或 url 传入，解析粒度可通过 detail 字段控制（可选 low、high、xhigh）[reference:13]。
• 上下文缓存：方舟提供 Context API（/context/chat/completions），用于缓存上下文数据，降低重复计算成本，适合多轮对话场景[reference:14]。

🖱️ 零门槛体验（无需编程）

如果你只是想先体验一下方舟的 API 调用，可以下载官方提供的 ark_quickstart_package.zip，解压后直接运行脚本：Windows 用户双击 run_windows.bat，macOS 用户双击 quickstart.sh，按提示输入 API Key 即可看到 AI 回复，全程无需安装任何编程环境[reference:15][reference:16]。

🔍 关键注意事项

• 模型 ID 或接入点 ID：调用时 model 字段可以填模型 ID（如 doubao-seed-2-1-pro-260628），也可以填你在控制台创建的推理接入点 ID（ep- 开头）。两者均可，但接入点 ID 能绑定特定配置[reference:17]。
• Base URL 区域：默认使用北京区域 ark.cn-beijing.volces.com。如果你在其他区域部署，需替换对应的 Base URL[reference:18]。
• 接口选择建议：新项目优先使用 Responses API，它的输入输出格式更简洁，上下文管理更高效；已有 OpenAI 代码的项目可直接迁移到 Chat API，只需修改 Base URL 和 API Key 即可[reference:19]。