本文帮助您了解并按照步骤完成 API 调用模型，包括如何配置环境，使用 SDK 调用模型服务，便于您了解如何通过代码使用模型能力，进而集成到您的工作或者应用中。
- 如果您想直接体验模型能力，访问模型广场。
- 如果您有模型调用经验，可以直接查看 API 参考ChatCompletions-文本生成或者模型教程文本生成。
- 如果您已有模型调用业务，期望迁移到 Doubao 大模型，可以参考兼容OpenAI API。
获取 API Key
- 打开并登录方舟控制台-API Key 管理。
- 单击创建 API Key 按钮。
- 在弹出框的名称文本框中确认/更改 API Key 名称，单击创建。
说明
- 请妥善保存好API Key，强烈建议您不要将其直接写入到调用模型的代码中。
- Access Key鉴权方式，请参见Access Key 签名鉴权。
配置 API Key 到环境变量
macOS
设置临时环境变量
您希望仅在当前会话中使用 API Key 环境变量，可以添加临时环境变量。
- 打开终端使用以下命令来设置环境变量，将
<YOUR_API_KEY>替换为您的方舟 API Key。
export ARK_API_KEY="<YOUR_API_KEY>"
- 执行以下命令，验证该环境变量是否生效。
echo $ARK_API_KEY
设置永久环境变量
您希望 API Key 环境变量在当前用户的所有新会话中生效，可以添加永久性环境变量。
- 打开在终端，使用以下命令，查看默认 Shell 类型。
echo $SHELL
/bin/zsh：默认的 Shell 类型是 Zsh（ Z shell）。/bin/bash：默认的 Shell 类型是 Bash。
Zsh
打开终端，使用以下命令来将环境变量设置追加到
~/.zshrc中。将<YOUR_API_KEY>替换为您的方舟 API Key。echo "export ARK_API_KEY='<YOUR_API_KEY>'" >> ~/.zshrc使用以下命令使更改生效。
source ~/.zshrc验证环境变量是否设置成功，在新的终端窗口，输入以下命令，如果返回您的 API Key，则表示设置成功。
echo $ARK_API_KEY
Bash
返回的是/bin/bash。
打开终端使用以下命令来将环境变量设置追加到
~/.bash_profile中。将<YOUR_API_KEY>替换为您的方舟 API Key。echo "export ARK_API_KEY='<YOUR_API_KEY>'" >> ~/.bash_profile使用以下命令使更改生效。
source ~/.bash_profile验证环境变量是否设置成功，在新的终端窗口，输入以下命令，如果返回您的 API Key，则表示设置成功。
echo $ARK_API_KEY
Linux
设置临时环境变量
如果您仅希望在当前会话中使用该环境变量，可以添加临时性环境变量。
- 打开终端使用以下命令来设置环境变量，将
<YOUR_API_KEY>替换为您的方舟 API Key。
export ARK_API_KEY="<YOUR_API_KEY>"
- 执行以下命令，验证该环境变量是否生效。
echo $ARK_API_KEY
设置永久环境变量
如果您希望 API Key 环境变量在当前用户的所有新会话中生效，可以添加永久性环境变量。
打开终端使用以下命令来将环境变量设置追加到
~/.bashrc中。将<YOUR_API_KEY>替换为您的方舟 API Key。echo "export ARK_API_KEY='<YOUR_API_KEY>'" >> ~/.bashrc使用以下命令使更改生效。
source ~/.bashrc验证环境变量是否设置成功，在新的终端窗口，输入以下命令，如果返回您的 API Key，则表示设置成功。
echo $ARK_API_KEY
Windows
设置临时环境变量
如果您仅希望在当前会话中使用该环境变量，可以添加临时性环境变量。
打开 CMD（命令提示符）或 PowerShell 。
输入以下命令来设置环境变量，将
<YOUR_API_KEY>替换为您的实际 API Key：set ARK_API_KEY="YOUR_API_KEY"验证环境变量是否设置成功，输入以下命令，如果返回您的 API Key，则表示设置成功。
echo %ARK_API_KEY%
设置永久环境变量
如果您希望 API Key 环境变量在当前用户的所有新会话中生效，可以添加永久性环境变量。
- 在 CMD 中，您可以使用
setx命令为当前用户设置永久性环境变量：
setx ARK_API_KEY "YOUR_API_KEY"
- 在 PowerShell 中，您可以使用以下命令为当前用户设置永久性环境变量：
[Environment]::SetEnvironmentVariable("ARK_API_KEY", "YOUR_API_KEY", [EnvironmentVariableTarget]::User)
- 验证环境变量是否设置成功，输入以下命令，如果返回您的 API Key，则表示设置成功。
echo %ARK_API_KEY%
推理接入点是方舟推出基于模型及其配置抽象的概念，通过推理接入点，您可以对模型服务进行灵活控制、精细监控、安全加固、风险防护等操作，获得更贴合业务、更安全的模型服务。
详细介绍请参见什么是推理接入点（Endpoint）。
- 打开并登录方舟控制台-在线推理。
- 单击创建推理接入点按钮，在打开的页面中根据引导配置推理接入点（最简的创建方式可以参考下图）。
说明
- 推荐您在模型选择时，选择旗舰模型 Doubao-pro 系列：字节跳动 ＞ Doubao-pro-32k 最新版本。
- 每位用户都会有一定额度的免费试用额度，不会产生模型调用费用，请放心使用。详细请参见免费推理额度说明。
- 创建完成后，可在在线推理页面的接入点列表中看到创建的推理接入点。接入点名称列即为您后续调用模型需要使用推理接入点ID。
Python | Curl | Go | Java
您可以根据你的业务或者本地环境情况，选择调用模型推理服务的语言。
Python
Python 安装
检查并安装 Python 版本，Python 版本需要 3.7 或以上。
您可以在终端中输入以下命令查看 Python 安装版本。
python -V
如果运行失败，您可以尝试使用下面命令再运行。
python3 -V
如果未安装或者版本不满足，请参考 Python 安装教程安装，注意选择版本 3.7 及以上版本。
方舟 Python SDK
跳转使用OpenAI SDK
安装方舟 Python SDK。
您可以在终端中输入以下命令，安装/升级方舟 Python SDK。pip install -U 'volcengine-python-sdk[ark]'如果您本地安装错误，可以尝试使用下面命令安装方舟 Python SDK。
pip install -U volcengine-python-sdk[ark]创建一个文件命名为
ark_example.py，将下面示例代码拷贝进文件。import os from volcenginesdkarkruntime import Ark # 从环境变量中读取您的方舟API Key client = Ark(api_key=os.environ.get("ARK_API_KEY")) completion = client.chat.completions.create( # 替换 <YOUR_ENDPOINT_ID> 为您的方舟推理接入点 ID model="<YOUR_ENDPOINT_ID>", messages=[ {"role": "user", "content": "你好"} ] ) print(completion.choices[0].message)在终端窗口中，使用下面命令运行代码。稍等您可以在终端窗口中看到模型调用的返回结果，这样您就完成了您的首次方舟平台模型服务调用。
python ark_example.py
OpenAI SDK
跳转使用方舟 Python SDK
安装OpenAI SDK。
您可以在终端中输入以下命令，安装/升级方舟 OpenAI SDK。pip install -U openai创建一个文件命名为
ark_example.py，将下面示例代码拷贝进文件。import os from openai import OpenAI client = OpenAI( # 从环境变量中读取您的方舟API Key api_key=os.environ.get("ARK_API_KEY"), base_url="https://ark.cn-beijing.volces.com/api/v3", ) completion = client.chat.completions.create( # 替换 <YOUR_ENDPOINT_ID> 为您的方舟推理接入点 ID model="<YOUR_ENDPOINT_ID>", messages=[ {"role": "user", "content": "你好"} ] ) print(completion.choices[0].message)在终端窗口中，使用下面命令运行代码。稍等您可以在终端窗口中看到模型调用的返回结果，这样您就完成了您的首次方舟平台模型服务调用。
python ark_example.py
Curl
您可以通过 HTTP 方式直接调用方舟模型服务。
在终端窗口中，拷贝下面命令，并替换<YOUR_ENDPOINT_ID>为您的推理接入点 ID。稍等您可以在终端窗口中看到模型调用的返回结果。这样您就完成了您的首次方舟平台模型服务调用。
curl https://ark.cn-beijing.volces.com/api/v3/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $ARK_API_KEY" \ -d '{ "model": "<YOUR_ENDPOINT_ID>", "messages": [ { "role": "user", "content": "你好" } ] }'
如果返回错误码
{"error":{"code":"AuthenticationError","message":"The API key or AK/SK in the request is missing or invalid. requestId: 0217***，说明API Key中没有被正确设置到环境变量中，您可以直接替换$ARK_API_KEY为您的方舟 API Key ，再次运行命令。
Go
检查并安装 Go 版本，Go 版本需要 1.8 或以上。
go version如果未安装 Go 或者版本不满足要求，您可以访问 Go 语言官方网站下载并安装适合您操作系统的 Go 版本。请确保选择 1.18 或以上版本。
安装方舟 Go SDK。
火山方舟 Go SDK 使用 go mod 进行管理，如果本地工程没有初始化 go mod，您可以运行以下命令初始化 go mod。<your-project-name>替换为您的项目名称。# 如在文件夹 ark-example 下打开终端窗口，运行命令go mod init ark-example go mod init <your-project-name>创建一个
main.go文件，将下面代码拷贝到文件中，并替换<YOUR_ENDPOINT_ID>。package main import ( "context" "fmt" "os" "github.com/volcengine/volcengine-go-sdk/service/arkruntime" "github.com/volcengine/volcengine-go-sdk/service/arkruntime/model" "github.com/volcengine/volcengine-go-sdk/volcengine" ) func main() { client := arkruntime.NewClientWithApiKey( //通过 os.Getenv 从环境变量中获取 ARK_API_KEY os.Getenv("ARK_API_KEY"), ) // 创建一个上下文，通常用于传递请求的上下文信息，如超时、取消等 ctx := context.Background() // 构建聊天完成请求，设置请求的模型和消息内容 req := model.ChatCompletionRequest{ // 需要替换 <YOUR_ENDPOINT_ID> 为您的推理接入点 ID Model: "<YOUR_ENDPOINT_ID>", Messages: []*model.ChatCompletionMessage{ { // 消息的角色为用户 Role: model.ChatMessageRoleUser, Content: &model.ChatCompletionMessageContent{ StringValue: volcengine.String("你好"), }, }, }, } // 发送聊天完成请求，并将结果存储在 resp 中，将可能出现的错误存储在 err 中 resp, err := client.CreateChatCompletion(ctx, req) if err!= nil { // 若出现错误，打印错误信息并终止程序 fmt.Printf("standard chat error: %v\n", err) return } // 打印聊天完成请求的响应结果 fmt.Println(*resp.Choices[0].Message.Content.StringValue) }在终端窗口中，使用下面命令更新项目的依赖项。
go mod tidy在终端窗口中，使用下面命令运行代码。稍等您可以在终端窗口中看到模型调用的返回结果。这样您就完成了您的首次方舟平台模型服务调用。
go run main.go
Java
检查并安装 Java 版本，Java 版本需要 1.8 或以上。
java -version如果未安装 Java 或者版本不满足要求，您可以访问 Oracle 官方网站下载并安装适合您操作系统的 Java 版本。请确保选择 1.8 或以上版本。
安装方舟 Java JDK。
火山方舟 Java SDK 支持通过 Maven 和 Gradle 两种方式安装。- 通过 Maven 安装：在项目的
pom.xml文件中添加以下依赖配置。
... <dependency> <groupId>com.volcengine</groupId> <artifactId>volcengine-java-sdk-ark-runtime</artifactId> <version>LATEST</version> </dependency> ...打开终端并进入项目根目录，运行下面命令，来安装依赖项。
mvn clean install- 通过 Gradle 安装：在项目的
build.gradle文件中，在dependencies部分添加以下依赖。
implementation 'com.volcengine:volcengine-java-sdk-ark-runtime:LATEST'- 通过 Maven 安装：在项目的
将下面的示例代码拷贝到您的项目中，并替换您的推理接入点 ID 。
package com.ark.example; import com.volcengine.ark.runtime.model.completion.chat.ChatCompletionRequest; import com.volcengine.ark.runtime.model.completion.chat.ChatMessage; import com.volcengine.ark.runtime.model.completion.chat.ChatMessageRole; import com.volcengine.ark.runtime.service.ArkService; import java.util.ArrayList; import java.util.List; /** * 这是一个示例类，展示了如何使用ArkService来完成聊天功能。 */ public class ChatCompletionsExample { public static void main(String[] args) { // 从环境变量中获取API密钥 String apiKey = System.getenv("ARK_API_KEY"); // 创建ArkService实例 ArkService arkService = ArkService.builder().apiKey(apiKey).build(); // 初始化消息列表 List<ChatMessage> chatMessages = new ArrayList<>(); // 创建用户消息 ChatMessage userMessage = ChatMessage.builder() .role(ChatMessageRole.USER) // 设置消息角色为用户 .content("你好") // 设置消息内容 .build(); // 将用户消息添加到消息列表 chatMessages.add(userMessage); // 创建聊天完成请求 ChatCompletionRequest chatCompletionRequest = ChatCompletionRequest.builder() .model("<YOUR_ENDPOINT_ID>")// 需要替换为您的推理接入点ID .messages(chatMessages) // 设置消息列表 .build(); // 发送聊天完成请求并打印响应 try { // 获取响应并打印每个选择的消息内容 arkService.createChatCompletion(chatCompletionRequest) .getChoices() .forEach(choice -> System.out.println(choice.getMessage().getContent())); } catch (Exception e) { System.out.println("请求失败: " + e.getMessage()); } finally { // 关闭服务执行器 arkService.shutdownExecutor(); } } }编译您的Java项目并运行，稍等您可以在终端窗口中看到模型调用的返回结果。这样您就完成了您的首次方舟平台模型服务调用。