火山方舟
火山方舟
API参考
请输入
对话(Chat) API
Responses API
Responses 流式响应事件
System One API（beta）
3D生成 API
向量化 API
Managed Agents API
Environments
Sessions
分词 API
管控面 API
管理 API Key
管理 Agent / Coding Plan
管理 Coding Plan
管理模型限流
管理推理接入点（Endpoint）
- 文档首页
火山方舟其他说明SDK 常见使用示例
复制全文
下载 pdfSDK 常见使用示例
文档反馈
问问助手当您使用官方 SDK 时，设置自定义header等典型的使用，可以参考本说明。
设置超时&重试次数
当您的网络环境不稳定或者响应时间较长的场景，可以设置超时和重试次数，以提高服务可用性。
- 超时设置（timeout）：适用于对响应时间较长的场景（如深度思考模型回复问题时间较长），避免请求时间超时导致服务中断，这里推荐30分钟（1800秒）。
- Python SDK：默认 60秒 连接超时（建立网络连接的最大等待时间），600 秒 socket 超时（连接建立后的数据传输超时）。
- Java SDK：默认 60秒 连接超时，600 秒 socket 超时。
- Go SDK：默认 600s 端到端的总超时（从请求发起至响应接收的总超时）。
- 重试次数（max_retries）：适用于网络不稳定场景，自动重试因瞬时故障（如网络波动）失败的请求，默认2次，即请求失败默认会再重试2次，您可以按需配置。
Python
Go
Java
import os
# Install the Ark SDK with: python -m pip install --upgrade arkruntime .
from arkruntime import Ark
client = Ark(
api_key=os.environ.get("ARK_API_KEY"),
# Allow enough time for long-running requests.
timeout=1800,
# Retry transient failures up to two times.
max_retries=2,
base_url="https://ark.cn-beijing.volces.com/api/v3",
)
import (
"os"
"time"
"github.com/volcengine/ark-runtime-go/arkruntime"
)
client := arkruntime.NewClientWithApiKey(
os.Getenv("ARK_API_KEY"),
arkruntime.WithTimeout(30*time.Minute), // Allow enough time for long-running requests.
arkruntime.WithRetryTimes(2), // Retry transient failures up to two times.
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
)
import java.time.Duration;
import com.volcengine.ark.runtime.service.ArkService;
public class ConfigureSdkTimeoutRetryExample {
public static void main(String[] args) {
String apiKey = System.getenv("ARK_API_KEY");
ArkService service = ArkService.builder()
.apiKey(apiKey)
.timeout(Duration.ofMinutes(30))
.connectTimeout(Duration.ofSeconds(20))
.retryTimes(2)
.baseUrl("https://ark.cn-beijing.volces.com/api/v3")
.build();
service.shutdownExecutor();
}
}
使用Access Key鉴权
当需要通过火山引擎云服务的标准鉴权体系（Access Key/Secret Key）认证时使用。
Python
Go
Java
import os
# 通过命令安装方舟SDK python -m pip install --upgrade arkruntime .
from arkruntime import Ark
client = Ark(
ak=os.environ.get("VOLC_ACCESSKEY"),
sk=os.environ.get("VOLC_SECRETKEY"),
# The base URL for model invocation .
base_url="https://ark.cn-beijing.volces.com/api/v3",
)
import (
"os"
"github.com/volcengine/ark-runtime-go/arkruntime"
)
client := arkruntime.NewClientWithAkSk(
os.Getenv("VOLC_ACCESSKEY"),
os.Getenv("VOLC_SECRETKEY"),
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"), // The base URL for model invocation .
)
import com.volcengine.ark.runtime.service.ArkService;
public class CreateArkClientExample1 {
public static void main(String[] args) {
String ak = System.getenv("VOLC_ACCESSKEY");
String sk = System.getenv("VOLC_SECRETKEY");
ArkService service = ArkService.builder().ak(ak).sk(sk)
// The base URL for model invocation .
.baseUrl("https://ark.cn-beijing.volces.com/api/v3")
.build();
}
// do your operation...
}
设置自定义 header
自定义的 header 字段采用键值对（key-value）结构，以对象形式呈现，具体格式示例如下：
{
"key1": "value1",
"key2": "value2",
...,
"keyN": "valueN"
}
问题定位
您可以在请求时，为多个请求设置 key 为 X-Client-Request-Id，value 配置为自定义的 ID，并提供 ID 给方舟售后团队，为您串联客户端和服务端日志，方便问题定位。
Python
Go
Java
import os
# 通过命令安装方舟SDK python -m pip install --upgrade arkruntime
from arkruntime import Ark
client = Ark(
api_key=os.environ.get("ARK_API_KEY"),
# The base URL for model invocation .
base_url="https://ark.cn-beijing.volces.com/api/v3",
)
completion = client.chat.completions.create(
# Replace with Model ID .
model = "doubao-seed-2-1-pro-260915",
messages = [
{"role": "user", "content": "Hello"},
],
# 自定义request id
extra_headers={"X-Client-Request-Id": "My-Request-Id"}
)
print(completion.choices[0].message.content)
package main
import (
"context"
"fmt"
"os"
"github.com/volcengine/ark-runtime-go/arkruntime"
arkmodel "github.com/volcengine/ark-runtime-go/arkruntime/model"
"github.com/volcengine/ark-runtime-go/arkruntime/model/chat"
)
func main() {
client := arkruntime.NewClientWithApiKey(
os.Getenv("ARK_API_KEY"),
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"), // The base URL for model invocation .
)
ctx := context.Background()
req := &chat.ChatCompletionRequest{
Model: "doubao-seed-2-1-pro-260915", //Replace with Model ID .
Messages: []chat.ChatCompletionRequestMessage{
userMessage("Hello"),
},
}
// 自定义request id
resp, err := client.CreateChatCompletion(
ctx,
req,
arkruntime.WithCustomHeader(arkmodel.ClientRequestHeader, "my-request-id"), // 自定义请求头
)
if err != nil {
fmt.Printf("standard chat error: %v\n", err)
return
}
fmt.Println(resp.Choices[0].Message.Content)
}
func userMessage(content string) chat.ChatCompletionRequestMessage {
return chat.ChatCompletionRequestMessage{
OneOf: chat.NewChatCompletionRequestUserMessageChatCompletionRequestMessageSum(
chat.ChatCompletionRequestUserMessage{
Role: chat.ChatCompletionRequestUserMessageRoleUser,
Content: chat.NewOptNilChatCompletionMessageContent(chat.NewStringChatCompletionMessageContent(content)),
},
),
}
}
package com.example;
import com.volcengine.ark.runtime.Const;
import com.volcengine.ark.runtime.models.chat.*;
import com.volcengine.ark.runtime.service.ArkService;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
public class ChatCompletionsExample3 {
public static void main(String[] args) {
String apiKey = System.getenv("ARK_API_KEY");
// The base URL for model invocation .
ArkService arkService = ArkService.builder().apiKey(apiKey)
.baseUrl("https://ark.cn-beijing.volces.com/api/v3")
.build();
final List<ChatCompletionRequestMessage> messages = new ArrayList<>();
final ChatCompletionRequestMessage userMessage = ChatCompletionRequestUserMessage.builder().role(ChatCompletionRequestMessageType.USER).content(ChatCompletionMessageContent.ofString("常见的十字花科植物有哪些？")).build();
messages.add(userMessage);
ChatCompletionRequest chatCompletionRequest = ChatCompletionRequest.builder()
.model("doubao-seed-2-1-pro-260915") //Replace with Model ID .
.messages(messages)
.build();
// 使用自定义的请求头
arkService.createChatCompletion(chatCompletionRequest, new HashMap<String, String>(){{put(Const.CLIENT_REQUEST_HEADER, "my_request_id");}}).getChoices().forEach(choice -> System.out.println(choice.getMessage().getContent()));
// shutdown service
arkService.shutdownExecutor();
}
}
加密数据
为了保证推理会话数据的传输安全，你可以为在线推理的会话数据加密。使能能力后，SDK 会对推理会话的内容进行加密。
- 版本要求：
- Python SDK：需要保证 arkruntime 版本为 0.5.0 及以上。参考升级 Python SDK升级 SDK。
- Java SDK：需要保证 com.volcengine:ark-runtime 版本为 0.5.0 及以上。参考升级 Java SDK升级 SDK。
- 能力支持：
- 仅支持文本生成模型和视觉理解图片理解模型请求。
- 图片仅支持 Base64 图片加密， URL 图片无法加密。
- 仅支持官方 Python SDK、Java SDK 的 Chat API 。
- 支持单轮、多轮会话，支持流式、非流式，同步、异步调用。
Python
Java
import os
# 通过命令安装方舟SDK python -m pip install --upgrade arkruntime
from arkruntime import Ark
client = Ark(
api_key=os.environ.get("ARK_API_KEY"),
# The base URL for model invocation .
base_url="https://ark.cn-beijing.volces.com/api/v3",
)
completion = client.chat.completions.create(
# Replace with Model ID .
model = "doubao-seed-2-1-pro-260915",
messages = [
{"role": "user", "content": "Hello"},
],
#按下述代码设置自定义header，免费开启推理会话应用层加密
extra_headers={'x-is-encrypted': 'true'}
)
print(completion.choices[0].message.content)
在 pom.xml 文件中增加以下配置：
<dependencies>
<!-- BouncyCastle 核心加密库（bcpkix依赖此包） -->
<dependency>
<groupId>org.bouncycastle</groupId>
<artifactId>bcprov-jdk18on</artifactId>
<version>1.78.1</version>
</dependency>
<!-- 包含PEMParser的模块（处理PEM格式证书） -->
<dependency>
<groupId>org.bouncycastle</groupId>
<artifactId>bcpkix-jdk18on</artifactId>
<version>1.78.1</version>
</dependency>
</dependencies>
代码示例如下：
package com.ark.sample;
import com.volcengine.ark.runtime.models.chat.*;
import com.volcengine.ark.runtime.service.ArkService;
import java.time.Duration;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.HashMap;
public class ChatCompletionsExample {
public static void main(String[] args) {
String apiKey = System.getenv("ARK_API_KEY");
ArkService service = ArkService.builder()
.apiKey(apiKey)
.baseUrl("https://ark.cn-beijing.volces.com/api/v3")
.timeout(Duration.ofSeconds(1800)) // Set the backend request processing timeout in seconds, recommended to be 1800 seconds or longer
.connectTimeout(Duration.ofSeconds(20)) // Set the connection timeout to 20 seconds
.retryTimes(2)// Set the retry count to 2
.build();
final List<ChatCompletionRequestMessage> messages = new ArrayList<>();
final ChatCompletionRequestMessage userMessage = ChatCompletionRequestUserMessage.builder().role(ChatCompletionRequestMessageType.USER).content(ChatCompletionMessageContent.ofString("Hello"))
.build();
messages.add(userMessage);
ChatCompletionRequest chatCompletionRequest = ChatCompletionRequest.builder()
.model("doubao-seed-2-1-pro-260915") //Replace with Model ID
.messages(messages)
.build();
// Set custom headers with the code below to enable application-layer encryption for inference sessions at no cost
Map<String, String> customHeaders = new HashMap<>();
customHeaders.put("x-is-encrypted", "true");
service.createChatCompletion(chatCompletionRequest, customHeaders).getChoices()
.forEach(choice -> System.out.println(choice.getMessage().getContent()));
// shutdown service
service.shutdownExecutor();
}
}
开启数据上报
该能力限时免费提供使用。
- 版本要求：如果请求上报未生效，需升级 SDK 到最新版本。
- 能力支持：仅支持 Responses API。
Python
Go
Java
import os
from arkruntime 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="<Endpoint_ID>",
input="hello",
extra_headers={'X-Fornax-Trace': 'true'}
)
print(response)
package main
import (
"context"
"fmt"
"os"
"github.com/volcengine/ark-runtime-go/arkruntime"
"github.com/volcengine/ark-runtime-go/arkruntime/model/responses"
)
func main() {
client := arkruntime.NewClientWithApiKey(
// Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey
os.Getenv("ARK_API_KEY"),
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
)
ctx := context.Background()
resp, err := client.CreateResponses(ctx, &responses.ResponsesRequest{
Model: "<Endpoint_ID>",
Input: responses.NewStringResponsesInput("hello"),
}, arkruntime.WithCustomHeader("X-Fornax-Trace", "true"))
if err != nil {
fmt.Printf("response error: %v\n", err)
return
}
fmt.Println(resp)
}
package com.ark.sample;
import com.volcengine.ark.runtime.service.ArkService;
import com.volcengine.ark.runtime.models.responses.*;
import java.util.HashMap;
import java.util.Map;
public class demo {
public static void main(String[] args) {
String apiKey = System.getenv("ARK_API_KEY");
// The base URL for model invocation
ArkService arkService = ArkService.builder().apiKey(apiKey)
.baseUrl("https://ark.cn-beijing.volces.com/api/v3")
.build();
ResponsesRequest request = ResponsesRequest.builder()
.model("<Endpoint_ID>")
.input(ResponsesInput.ofString("hello"))
.build();
Map<String, String> customHeaders = new HashMap<>();
customHeaders.put("X-Fornax-Trace", "true");
Response resp = arkService.createResponse(request, customHeaders);
System.out.println(resp);
arkService.shutdownExecutor();
}
}
单例请求
请使用单例方式请求模型服务，勿重复创建实例导致额外资源消耗。
Python
Go
Java
import os
# 通过命令安装方舟SDK python -m pip install --upgrade arkruntime
from arkruntime import Ark
client = Ark(
# Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey
api_key=os.environ.get("ARK_API_KEY"),
# The base URL for model invocation .
base_url="https://ark.cn-beijing.volces.com/api/v3",
)
# 请求1
completion = client.chat.completions.create(
model="doubao-seed-2-1-pro-260915",
messages=[
{"role": "user", "content": "Nice day"},
],
)
print(completion.choices[0].message.content)
# 请求2
completion = client.chat.completions.create(
model="doubao-seed-2-1-pro-260915",
messages=[
{"role": "user", "content": "Hello"},
],
)
print(completion.choices[0].message.content)
package main
import (
"context"
"fmt"
"os"
"github.com/volcengine/ark-runtime-go/arkruntime"
"github.com/volcengine/ark-runtime-go/arkruntime/model/chat"
)
func main() {
client := arkruntime.NewClientWithApiKey(
os.Getenv("ARK_API_KEY"),
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"), // The base URL for model invocation .
)
ctx := context.Background()
// 第一次请求
req1 := &chat.ChatCompletionRequest{
// Replace with Model ID .
Model: "doubao-seed-2-1-pro-260915",
Messages: []chat.ChatCompletionRequestMessage{
userMessage("Nice day"),
},
}
resp1, err := client.CreateChatCompletion(ctx, req1)
if err != nil {
fmt.Printf("standard chat error: %v\n", err)
return
}
fmt.Println(resp1.Choices[0].Message.Content)
// 第二次请求
req2 := &chat.ChatCompletionRequest{
// Replace with Model ID .
Model: "doubao-seed-2-1-pro-260915",
Messages: []chat.ChatCompletionRequestMessage{
userMessage("Hello"),
},
}
resp2, err := client.CreateChatCompletion(ctx, req2)
if err != nil {
fmt.Printf("standard chat error: %v\n", err)
return
}
fmt.Println(resp2.Choices[0].Message.Content)
}
func userMessage(content string) chat.ChatCompletionRequestMessage {
return chat.ChatCompletionRequestMessage{
OneOf: chat.NewChatCompletionRequestUserMessageChatCompletionRequestMessageSum(
chat.ChatCompletionRequestUserMessage{
Role: chat.ChatCompletionRequestUserMessageRoleUser,
Content: chat.NewOptNilChatCompletionMessageContent(chat.NewStringChatCompletionMessageContent(content)),
},
),
}
}
package com.example;
import com.volcengine.ark.runtime.models.chat.*;
import com.volcengine.ark.runtime.service.ArkService;
import java.util.ArrayList;
import java.util.List;
public class ChatCompletionsExample4 {
public static void main(String[] args) {
String apiKey = System.getenv("ARK_API_KEY");
// The base URL for model invocation .
ArkService arkService = ArkService.builder().apiKey(apiKey)
.baseUrl("https://ark.cn-beijing.volces.com/api/v3")
.build();
// 第一次请求
final List<ChatCompletionRequestMessage> messages1 = new ArrayList<>();
final ChatCompletionRequestMessage userMessage1 = ChatCompletionRequestUserMessage.builder().role(ChatCompletionRequestMessageType.USER).content(ChatCompletionMessageContent.ofString("今天天气不错？")).build();
messages1.add(userMessage1);
ChatCompletionRequest chatCompletionRequest1 = ChatCompletionRequest.builder()
.model("doubao-seed-2-1-pro-260915")// Replace with Model ID .
.messages(messages1)
.build();
arkService.createChatCompletion(chatCompletionRequest1).getChoices().forEach(choice -> System.out.println(choice.getMessage().getContent()));
// 第二次请求
final List<ChatCompletionRequestMessage> messages2 = new ArrayList<>();
final ChatCompletionRequestMessage userMessage2 = ChatCompletionRequestUserMessage.builder().role(ChatCompletionRequestMessageType.USER).content(ChatCompletionMessageContent.ofString("你好")).build();
messages2.add(userMessage2);
ChatCompletionRequest chatCompletionRequest2 = ChatCompletionRequest.builder()
.model("doubao-seed-2-1-pro-260915")// Replace with Model ID .
.messages(messages2)
.build();
arkService.createChatCompletion(chatCompletionRequest2).getChoices().forEach(choice -> System.out.println(choice.getMessage().getContent()));
// shutdown service
arkService.shutdownExecutor();
}
}
设置Base Url
初始化时 Ark、AsyncArk实例时，默认无需配置base_url参数，当需要连接非默认区域的服务端点时使用，示例如下。
Python
Go
Java
import os
# Install the Ark SDK with: python -m pip install --upgrade arkruntime .
from arkruntime import Ark
client = Ark(
api_key=os.environ.get("ARK_API_KEY"),
# Configure the service endpoint for the target region.
base_url="https://ark.cn-beijing.volces.com/api/v3",
)
import (
"os"
"github.com/volcengine/ark-runtime-go/arkruntime"
)
client := arkruntime.NewClientWithApiKey(
os.Getenv("ARK_API_KEY"),
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"), // Configure the service endpoint for the target region.
)
import com.volcengine.ark.runtime.service.ArkService;
public class CreateArkClientExample {
public static void main(String[] args) {
String apiKey = System.getenv("ARK_API_KEY");
ArkService service = ArkService.builder()
.apiKey(apiKey)
.baseUrl("https://ark.cn-beijing.volces.com/api/v3")
// The base URL for model invocation .
.build();
}
// do your operation...
}
最近更新时间：2026.10.09 14:36:34
这个页面对您有帮助吗？
有用
有用
无用
无用