火山方舟怎麼呼叫大模型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]。