火山方舟
火山方舟
文档指南
请输入
调用
视频生成
工具调用
使用 Responses API
推理
训练
模型精调
Managed Agents
配置 Agent 环境
管理 Agent 上下文
高级能力
- 文档首页
火山方舟调用进阶使用文件输入(Files API)
复制全文
下载 pdf文件输入(Files API)
文档反馈
问问助手Files API 作为文件管理接口，提供文件的上传、检索、列表查询及删除能力。
在多模态理解场景中，Files API 与 Responses API、Chat API 结合使用，具备以下优势：
- 大文件适配：文件存储在方舟平台托管的默认存储空间中时，支持最大 512 MB 文件的上传；文件存储在用户指定的火山引擎对象存储 TOS Bucket 中时，支持最大 2 GB 的视频文件的上传，从而满足大文件处理需求。
- 重复使用：支持通过 File ID 在多次请求中重复使用文件，避免重复上传，节省公网下载时延。
- 缩短推理时长：解耦数据预处理与模型推理环节，避免每次请求时重新上传内容，减少预处理导致的时延。
前提条件
查看 API 文档
Files API 使用示例
上传文件
使用 Files API 可以上传图片、视频、音频、文档等类型的文件，上传成功后将返回 File ID。File ID 支持在多次请求中重复使用，而不需要重新上传内容，节省公网下载时延。如果文件大于 50 MB，或者要在多个请求中重复使用该文件，可以使用 Files API 上传文件，然后使用 File ID 发起请求。
- 未传入 tos 参数：文件存储至方舟平台托管的默认存储空间。
- 传入 tos 参数：文件存储至用户指定的火山引擎对象存储 TOS Bucket。
文件上传方式
Files API 支持二进制文件、文件 URL 两种方式上传文件。
- file（二进制文件）：要上传的本地文件。文件可存储至方舟平台默认托管存储空间，或用户指定的火山引擎 TOS 存储桶。
- url（文件 URL）：支持 HTTP/HTTPS URL、TOS URI 两种方式。
- HTTP/HTTPS URL：公网可直接访问的文件 URL，请确保文件 URL 可被访问。文件可存储至方舟平台默认托管存储空间，或用户指定的火山引擎 TOS 存储桶。
- TOS URI：对象存储 TOS 专属的资源定位标识，格式为 tos://<bucket>/<prefix>/<file_name>。使用该方式时，文件仅支持存储至火山引擎 TOS 存储桶。
file 上传方式
- 文件存储至方舟平台默认托管存储空间
- CurlPython SDKGo SDKJava SDK兼容 OpenAI SDKcurl https://ark.cn-beijing.volces.com/api/v3/files \-H "Authorization: Bearer $ARK_API_KEY" \-F 'purpose=user_data' \-F 'file=@/Users/doc/demo.mp4' \-F 'preprocess_configs[video][fps]=0.3'响应参数如下：{"object": "file","id": "file-20251018114827-6zgrb","purpose": "user_data","filename": "demo.mp4","bytes": 695110,"mime_type": "video/mp4","created_at": 1760759307,"expire_at": 1761364107,"status": "processing","preprocess_configs": {"video": {"fps": 0.3}}}import osfrom arkruntime import Arkclient = Ark(base_url='https://ark.cn-beijing.volces.com/api/v3',api_key=os.getenv('ARK_API_KEY'))file = client.files.create(# replace with your local video pathfile=open("/Users/doc/demo.mp4", "rb"),purpose="user_data",preprocess_configs={"video": {"fps": 0.3, # define the sampling fps of the video, default is 1.0}})print(file)package mainimport ("context""fmt""os""github.com/volcengine/ark-runtime-go/arkruntime""github.com/volcengine/ark-runtime-go/arkruntime/model/file")func main() {client := arkruntime.NewClientWithApiKey(os.Getenv("ARK_API_KEY"),arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),)ctx := context.Background()data, err := os.Open("/Users/doc/demo.mp4")if err != nil {fmt.Printf("read file error: %v\n", err)return}fileInfo, err := client.UploadFile(ctx, &file.FileCreateRequest{Purpose: file.PurposeUserData,PreprocessConfigs: file.NewOptPreprocessConfigs(file.PreprocessConfigs{Video: file.NewOptVideo(file.Video{Fps: file.NewOptFloat64(0.3),}),}),}, data)if err != nil {fmt.Printf("upload file error: %v", err)return}fmt.Printf("file info: %v\n", fileInfo)}package com.ark.sample;import com.volcengine.ark.runtime.models.file.*;import com.volcengine.ark.runtime.models.file.FileObject;import com.volcengine.ark.runtime.models.file.PreprocessConfigs;import com.volcengine.ark.runtime.models.file.FileCreateRequest;import com.volcengine.ark.runtime.models.file.Video;import com.volcengine.ark.runtime.service.ArkService;import java.io.File;public class demo {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").build();System.out.println("===== Upload File Example=====");FileObject fileMeta;fileMeta = service.uploadFile(FileCreateRequest.builder() // replace with your video file path.purpose(Purpose.USER_DATA).preprocessConfigs(PreprocessConfigs.builder().video(Video.builder().fps(0.3).build()).build()).build(), new File("/Users/doc/demo.mp4"));System.out.println("Uploaded file Meta: " + fileMeta);service.shutdownExecutor();}}import osfrom openai import OpenAIclient = OpenAI(base_url='https://ark.cn-beijing.volces.com/api/v3',api_key=os.getenv('ARK_API_KEY'))file = client.files.create(# replace with your local video pathfile=open("/Users/doc/demo.mp4", "rb"),purpose="user_data",extra_body={"preprocess_configs":{"video": {"fps": 0.3}}})print(file)
- 文件存储至火山引擎对象存储 TOS Bucket：
- CurlPython SDKGo SDKJava SDKcurl https://ark.cn-beijing.volces.com/api/v3/files \-H "Authorization: Bearer $ARK_API_KEY" \-F 'purpose=user_data' \-F 'file=@/Users/doc/demo.mp4' \-F 'preprocess_configs[video][fps]=0.3' \-F "tos[bucket]=my-bucket" \-F "tos[prefix]=ark-files/"import osfrom arkruntime import Arkclient = Ark(base_url='https://ark.cn-beijing.volces.com/api/v3',api_key=os.getenv('ARK_API_KEY'))file = client.files.create(file=open("/Users/doc/demo.mp4", "rb"),purpose="user_data",preprocess_configs={"video": {"fps": 0.3}},tos={"bucket": "my-bucket","prefix": "ark-files/"})print(file)package mainimport ("context""fmt""os""github.com/volcengine/ark-runtime-go/arkruntime""github.com/volcengine/ark-runtime-go/arkruntime/model/file")func main() {client := arkruntime.NewClientWithApiKey(os.Getenv("ARK_API_KEY"),arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),)ctx := context.Background()data, err := os.Open("/Users/doc/demo.mp4")if err != nil {fmt.Printf("read file error: %v\n", err)return}fileInfo, err := client.UploadFile(ctx, &file.FileCreateRequest{Purpose: file.PurposeUserData,Tos: file.NewOptTosStorage(file.TosStorage{Bucket: file.NewOptString("my-bucket"),Prefix: file.NewOptString("ark-files/"),}),PreprocessConfigs: file.NewOptPreprocessConfigs(file.PreprocessConfigs{Video: file.NewOptVideo(file.Video{Fps: file.NewOptFloat64(0.3),}),}),}, data)if err != nil {fmt.Printf("upload file error: %v", err)return}fmt.Printf("file info: %v\n", fileInfo)}package com.ark.sample;import com.volcengine.ark.runtime.models.file.*;import com.volcengine.ark.runtime.service.ArkService;import java.io.File;public class demo {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").build();System.out.println("===== Upload File Example =====");FileObject fileMeta;fileMeta = service.uploadFile(FileCreateRequest.builder().purpose(Purpose.USER_DATA).tos(TosStorage.builder().bucket("my-bucket").prefix("ark-files/").build()).preprocessConfigs(PreprocessConfigs.builder().video(Video.builder().fps(0.3).build()).build()).build(), new File("/Users/doc/demo.mp4"));System.out.println("Uploaded file Meta: " + fileMeta);service.shutdownExecutor();}}
HTTP/HTTPS URL 上传方式
- 文件存储至方舟平台默认托管存储空间
- CurlPython SDKGo SDKJava SDKcurl -X POST "https://ark.cn-beijing.volces.com/api/v3/files" \-H "Authorization: Bearer $ARK_API_KEY" \-F "purpose=user_data" \-F "url=https://example.com/docs/demo_img.png"import osfrom arkruntime import Arkclient = Ark(base_url='https://ark.cn-beijing.volces.com/api/v3',api_key=os.getenv('ARK_API_KEY'))file = client.files.create(purpose="user_data",url="https://example.com/docs/demo_img.png")print(file)package mainimport ("context""fmt""os""github.com/volcengine/ark-runtime-go/arkruntime""github.com/volcengine/ark-runtime-go/arkruntime/model/file")func main() {client := arkruntime.NewClientWithApiKey(os.Getenv("ARK_API_KEY"),arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),)ctx := context.Background()fileInfo, err := client.UploadFile(ctx, &file.FileCreateRequest{Purpose: file.PurposeUserData,URL: file.NewOptString("https://example.com/docs/demo_img.png"),}, nil)if err != nil {fmt.Printf("upload file error: %v", err)return}fmt.Printf("file info: %v\n", fileInfo)}package com.ark.sample;import com.volcengine.ark.runtime.model.files.*;import com.volcengine.ark.runtime.service.ArkService;public class demo {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").build();System.out.println("===== Upload File Example =====");FileMeta fileMeta;try {fileMeta = service.uploadFile(UploadFileRequest.builder().url("https://example.com/docs/demo_img.png").purpose("user_data").build());System.out.println("Uploaded file Meta: " + fileMeta);} catch (Exception e) {e.printStackTrace();}service.shutdownExecutor();}}
- 文件存储至火山引擎对象存储 TOS Bucket
- CurlPython SDKGo SDKJava SDKcurl -X POST "https://ark.cn-beijing.volces.com/api/v3/files" \-H "Authorization: Bearer $ARK_API_KEY" \-F "purpose=user_data" \-F "url=https://example.com/docs/demo_img.png" \-F "tos[bucket]=my-bucket" \-F "tos[prefix]=ark-files/"import osfrom arkruntime import Arkclient = Ark(base_url='https://ark.cn-beijing.volces.com/api/v3',api_key=os.getenv('ARK_API_KEY'))file = client.files.create(url="https://example.com/docs/demo_img.png",purpose="user_data",tos={"bucket": "my-bucket","prefix": "ark-files/"})print(file)package mainimport ("context""fmt""os""github.com/volcengine/ark-runtime-go/arkruntime""github.com/volcengine/ark-runtime-go/arkruntime/model/file")func main() {client := arkruntime.NewClientWithApiKey(os.Getenv("ARK_API_KEY"),arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),)ctx := context.Background()fileInfo, err := client.UploadFile(ctx, &file.FileCreateRequest{Purpose: file.PurposeUserData,URL: file.NewOptString("https://example.com/docs/demo_img.png"),Tos: file.NewOptTosStorage(file.TosStorage{Bucket: file.NewOptString("my-bucket"),Prefix: file.NewOptString("ark-files/"),}),}, nil)if err != nil {fmt.Printf("upload file error: %v", err)return}fmt.Printf("file info: %v\n", fileInfo)}package com.ark.sample;import com.volcengine.ark.runtime.model.files.*;import com.volcengine.ark.runtime.service.ArkService;public class demo {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").build();System.out.println("===== Upload File Example =====");FileMeta fileMeta;try {fileMeta = service.uploadFile(UploadFileRequest.builder().url("https://example.com/docs/demo_img.png").purpose("user_data").tos(TosStorage.builder().bucket("my-bucket").prefix("ark-files/").build()).build());System.out.println("Uploaded file Meta: " + fileMeta);} catch (Exception e) {e.printStackTrace();}service.shutdownExecutor();}}
TOS URI 上传方式
传入 TOS URI 时，必须将文件存储到火山引擎对象存储 TOS Bucket 中。其中：
- url 用于指定待读取的源文件位置，即火山引擎对象存储 TOS Bucket 中的已有文件。
- tos[bucket] 和 tos[prefix] 用于指定上传文件至火山引擎对象存储 TOS Bucket 中的存储桶和存储路径。
如果 url 指向其他账号的火山引擎对象存储 TOS Bucket，当前调用 Files API 的账号或项目需要具备该 Bucket 的读取权限。跨账号访问 TOS Bucket 时，请参考 授权其他账号访问存储桶 完成授权后再调用 Files API。
Curl
Python SDK
Go SDK
Java SDK
curl -X POST "https://ark.cn-beijing.volces.com/api/v3/files" \
-H "Authorization: Bearer $ARK_API_KEY" \
-F "purpose=user_data" \
-F "url=tos://my-bucket/source/raw_video.mp4" \
-F "tos[bucket]=my-bucket" \
-F "tos[prefix]=ark-files/"
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')
)
file = client.files.create(
url="tos://my-bucket/source/raw_video.mp4",
purpose="user_data",
tos={
"bucket": "my-bucket",
"prefix": "ark-files/"
}
)
print(file)
package main
import (
"context"
"fmt"
"os"
"github.com/volcengine/ark-runtime-go/arkruntime"
"github.com/volcengine/ark-runtime-go/arkruntime/model/file"
)
func main() {
client := arkruntime.NewClientWithApiKey(
os.Getenv("ARK_API_KEY"),
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
)
ctx := context.Background()
fileInfo, err := client.UploadFile(ctx, &file.FileCreateRequest{
Purpose: file.PurposeUserData,
URL: file.NewOptString("tos://my-bucket/source/raw_video.mp4"),
Tos: file.NewOptTosStorage(file.TosStorage{
Bucket: file.NewOptString("my-bucket"),
Prefix: file.NewOptString("ark-files/"),
}),
}, nil)
if err != nil {
fmt.Printf("upload file error: %v", err)
return
}
fmt.Printf("file info: %v\n", fileInfo)
}
package com.ark.sample;
import com.volcengine.ark.runtime.model.files.*;
import com.volcengine.ark.runtime.service.ArkService;
public class demo {
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")
.build();
System.out.println("===== Upload File Example =====");
FileMeta fileMeta;
try {
fileMeta = service.uploadFile(
UploadFileRequest.builder()
.url("tos://my-bucket/source/raw_video.mp4")
.purpose("user_data")
.tos(TosStorage.builder()
.bucket("my-bucket")
.prefix("ark-files/")
.build())
.build());
System.out.println("Uploaded file Meta: " + fileMeta);
} catch (Exception e) {
e.printStackTrace();
}
service.shutdownExecutor();
}
}
在大视频理解场景下，通过 Files API 以 url 方式上传，并传入 tos 参数时，视频文件单文件最大支持 2GB（该能力仅适用于视频文件，其他类型文件容量限制仍保持 512 MB）。文件上传后会进入异步处理流程，需待文件状态变为 active 后方可使用。
Curl
Python SDK
Go SDK
Java SDK
curl -X POST "https://ark.cn-beijing.volces.com/api/v3/files" \
-H "Authorization: Bearer $ARK_API_KEY" \
-F "purpose=user_data" \
-F "url=tos://my-bucket/videos/long-video.mp4" \
-F "tos[bucket]=my-bucket" \
-F "tos[prefix]=ark-files/" \
-F "preprocess_configs[video][model]=doubao-seed-2-1-pro-260915" \
-F "preprocess_configs[video][max_video_tokens]=200000" \
-F "preprocess_configs[video][min_frames]=16"
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')
)
file = client.files.create(
url="tos://my-bucket/videos/long-video.mp4",
purpose="user_data",
tos={
"bucket": "my-bucket",
"prefix": "ark-files/"
},
preprocess_configs={
"video": {
"model": "doubao-seed-2-1-pro-260915",
"max_video_tokens": 200000,
"min_frames": 16
}
}
)
print(file)
package main
import (
"context"
"fmt"
"os"
"github.com/volcengine/volcengine-go-sdk/service/arkruntime"
"github.com/volcengine/volcengine-go-sdk/service/arkruntime/model/file"
"github.com/volcengine/volcengine-go-sdk/volcengine"
)
func main() {
client := arkruntime.NewClientWithApiKey(
os.Getenv("ARK_API_KEY"),
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
)
ctx := context.Background()
fileInfo, err := client.UploadFile(ctx, &file.UploadFileRequest{
Purpose: file.PurposeUserData,
URL: volcengine.String("tos://my-bucket/videos/long-video.mp4"),
Tos: &file.TosStorage{
Bucket: volcengine.String("my-bucket"),
Prefix: volcengine.String("ark-files/"),
},
PreprocessConfigs: &file.PreprocessConfigs{
Video: &file.Video{
Model: volcengine.String("doubao-seed-2-1-pro-260915"),
MaxVideoTokens: volcengine.Int64(200000),
MinFrames: volcengine.Int64(16),
},
},
})
if err != nil {
fmt.Printf("upload file error: %v", err)
return
}
fmt.Printf("file info: %v\n", fileInfo)
}
package com.ark.sample;
import com.volcengine.ark.runtime.model.files.*;
import com.volcengine.ark.runtime.service.ArkService;
public class demo {
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")
.build();
System.out.println("===== Upload File Example =====");
FileMeta fileMeta;
try {
fileMeta = service.uploadFile(
UploadFileRequest.builder()
.url("tos://my-bucket/videos/long-video.mp4")
.purpose("user_data")
.tos(TosStorage.builder()
.bucket("my-bucket")
.prefix("ark-files/")
.build())
.preprocessConfigs(PreprocessConfigs.builder()
.video(Video.builder()
.model("doubao-seed-2-1-pro-260915")
.maxVideoTokens(200000L)
.minFrames(16L)
.build())
.build())
.build());
System.out.println("Uploaded file Meta: " + fileMeta);
} catch (Exception e) {
e.printStackTrace();
}
service.shutdownExecutor();
}
}
文件存储限制
对比项 | 方舟平台托管的默认存储空间 | 火山引擎对象存储 TOS Bucket |
对比项 | 方舟平台托管的默认存储空间 | 火山引擎对象存储 TOS Bucket |
授权要求 | 无需额外授权。 | |
单文件大小 | 512 MB | 视频文件 2 GB，其他类型文件 512 MB |
总存储容量 | 20 GB | 无限制 |
存储时间 | 默认存储 7 天，支持通过 expire_at 参数自定义存储有效期，取值范围为 1-30 天。 针对高频存储场景，建议通过缩短文件存储时长、主动调用删除接口清理低频文件这两种方式，做好存储空间的主动管理。 | 默认存储 7 天，支持通过 expire_at 参数自定义存储有效期，取值范围为 1-30 天。 |
对象操作限制 | 对象被托管后，仅支持读取，不支持通过 TOS 控制台或 TOS API 删除、覆盖或修改对象。命中该对象的生命周期删除、覆盖式复制等异步写、删、改操作，同样受到托管保护限制。如需删除文件，请调用 Files API 删除。参考删除文件。 |
文件预处理
使用 Files API 上传文件时，接口会根据上传的文件类型进行预处理。
- 视频文件：默认会按 1 帧/秒（FPS）的速率提取选段，可通过 preprocess_configs.video.fps 设置自定义帧速率。长视频且画面变化较小时，可设置较低的 FPS 值；需精细捕捉画面变化时，可设置较高的 FPS 值。同时可通过min_frame_tokens、max_frame_tokens、max_video_tokens 用于控制单帧压缩与整体视频信息保留策略。文件预处理后，在 Responses API 中使用 File ID，可以缩短推理时长。
- PDF 文件：会分页来处理成多图，在预处理时不会对拆分的图片做分辨率缩放，以确保图片能够完整且清晰地保留 PDF 文件中的原始信息。
说明
传入 tos 参数时，文件预处理产物将保存至参数指定的 TOS 路径。例如，若请求中配置 tos[bucket]=my-bucket、tos[prefix]=ark-files/，则预处理产物存储路径为 my-bucket/ark-files/ark_processed/{file_id}/ 目录下，其中 {file_id} 为本次上传文件的 ID。
预处理超时限制
使用 Files API 进行文件预处理的超时限制为 5 min，超时通常会受视频时长、PDF 页数、单页像素、单帧像素、音频时长等因素影响。
超时解决方案：
优先检查是否存在像素过大的问题，其中对 1080p 视频抽帧操作容易导致超时，建议压缩至 720p 及以下。
模型推理阶段会压缩分辨率，所以提升原始像素对最终效果无增益。
视频压缩工具及命令
ffmpeg -i input.mp4 \
-vf "scale=1280:720" \
-c:v libx264 -crf 23 \
-c:a aac -b:a 128k \
output_720p.mp4
文件类型
Files API 支持多种文件类型，具体如下。
文件类型 | 文件格式 | MIME 类型 |
文件类型 | 文件格式 | MIME 类型 |
图片 | .jpg、.jpeg、.png、.gif、.webp、.bmp、.tiff、.ico、.icns、.sgi、.jp2、.heic、.heif | image/jpeg、image/png、image/gif、image/webp、image/bmp、image/tiff、image/x-icon、image/x-icns、image/sgi、image/jp2、image/heic、image/heic |
视频 | .mp4、.avi、.mov | video/mp4、video/x-msvideo、video/quicktime |
文档 | .pdf | application/pdf |
音频 | .mp3、.wav、.aac、.m4a | audio/mpeg、audio/wav、audio/aac、audio/x-m4a |
说明
管理文件
检索文件
文件上传成功后将自动触发预处理流程。接口返回 file_id 后，可通过调用检索文件接口查询文件处理状态；当状态 status 变为 active 时，才可以在 Responses API、Chat API 中通过 file_id 方式实现多模态理解。
Curl
Python SDK
Go SDK
Java SDK
兼容 OpenAI SDK
curl https://ark.cn-beijing.volces.com/api/v3/files/file-20251119**** \
-H "Authorization: Bearer $ARK_API_KEY"
import os
from arkruntime import Ark
# Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey
api_key = os.getenv('ARK_API_KEY')
client = Ark(
base_url='https://ark.cn-beijing.volces.com/api/v3',
api_key=api_key,
)
# Retrieve file
response = client.files.retrieve(
file_id="file-20251119****"
)
print(response)
package main
import (
"context"
"fmt"
"os"
"github.com/volcengine/ark-runtime-go/arkruntime"
)
func main() {
client := arkruntime.NewClientWithApiKey(
os.Getenv("ARK_API_KEY"),
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
)
ctx := context.Background()
fileInfo, err := client.RetrieveFile(ctx, "file-20251119****")
if err != nil {
fmt.Printf("get file status error: %v", err)
return
}
fmt.Printf("file info: %v", fileInfo)
}
package com.ark.sample;
import com.volcengine.ark.runtime.models.file.*;
import com.volcengine.ark.runtime.service.ArkService;
public class demo {
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")
.build();
// Retrieve the file metadata.
FileObject fileMeta = service.retrieveFile("file-20251119****");
System.out.println("Retrieve File:" + fileMeta);
service.shutdownExecutor();
}
}
import os
from openai import OpenAI
api_key = os.getenv('ARK_API_KEY')
client = OpenAI(
base_url='https://ark.cn-beijing.volces.com/api/v3',
api_key=api_key,
)
# Retrieve the file metadata.
response = client.files.retrieve(
file_id="file-20251119****"
)
print(response)
查询文件列表
Curl
Python SDK
Go SDK
Java SDK
兼容 OpenAI SDK
curl https://ark.cn-beijing.volces.com/api/v3/files \
-H "Authorization: Bearer $ARK_API_KEY"
import os
from arkruntime import Ark
api_key = os.getenv('ARK_API_KEY')
client = Ark(
base_url='https://ark.cn-beijing.volces.com/api/v3',
api_key=api_key,
)
response = client.files.list()
print(response)
package main
import (
"context"
"fmt"
"os"
"github.com/volcengine/ark-runtime-go/arkruntime"
"github.com/volcengine/ark-runtime-go/arkruntime/model/file"
)
func main() {
client := arkruntime.NewClientWithApiKey(
os.Getenv("ARK_API_KEY"),
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
)
ctx := context.Background()
fileInfo, err := client.ListFiles(ctx, &file.FilesListParams{})
if err != nil {
fmt.Printf("get file List error: %v", err)
return
}
fmt.Printf("file List: %v", fileInfo)
}
package com.ark.sample;
import com.volcengine.ark.runtime.models.file.*;
import com.volcengine.ark.runtime.service.ArkService;
public class demo {
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")
.build();
FileListRequest request = new FileListRequest();
FileListResponse listFiles = service.listFiles(request);
System.out.println("List Files:" + listFiles);
service.shutdownExecutor();
}
}
import os
from openai import OpenAI
api_key = os.getenv('ARK_API_KEY')
client = OpenAI(
base_url='https://ark.cn-beijing.volces.com/api/v3',
api_key=api_key,
)
response = client.files.list()
print(response)
删除文件
- 缩短文件存储时长：上传成功的文件默认存储 7 天，可以通过 expire_at 参数自定义存储有效期，取值范围为 1-30 天。文件超过存储有效期后会自动删除，参数设置请参见上传文件。
- 主动调用删除接口清理低频文件：通过 Files API 删除已上传的文件，使用示例如下。
Curl
Python SDK
Go SDK
Java SDK
兼容 OpenAI SDK
curl https://ark.cn-beijing.volces.com/api/v3/files/file-20251014**** \
-X DELETE \
-H "Authorization: Bearer $ARK_API_KEY"
import os
from arkruntime import Ark
api_key = os.getenv('ARK_API_KEY')
client = Ark(
base_url='https://ark.cn-beijing.volces.com/api/v3',
api_key=api_key,
)
if __name__ == "__main__":
try:
response = client.files.delete(
file_id="file-20251014****"
)
print(response)
except Exception as e:
print(f"failed to delete response: {e}")
package main
import (
"context"
"fmt"
"os"
"github.com/volcengine/ark-runtime-go/arkruntime"
)
func main() {
client := arkruntime.NewClientWithApiKey(
os.Getenv("ARK_API_KEY"),
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
)
ctx := context.Background()
fileInfo, err := client.DeleteFile(ctx, "file-20251014****")
if err != nil {
fmt.Printf("delete file error: %v", err)
return
}
fmt.Printf(" delete file: %v", fileInfo)
}
package com.ark.sample;
import com.volcengine.ark.runtime.models.file.*;
import com.volcengine.ark.runtime.service.ArkService;
public class demo {
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")
.build();
// Delete the file.
FileDeleted deleteFile = service.deleteFile("file-20251014****");
System.out.println("Delete File:" + deleteFile);
service.shutdownExecutor();
}
}
import os
from openai import OpenAI
api_key = os.getenv('ARK_API_KEY')
client = OpenAI(
base_url='https://ark.cn-beijing.volces.com/api/v3',
api_key=api_key,
)
if __name__ == "__main__":
try:
response = client.files.delete(
file_id="file-20251014****"
)
print(response)
except Exception as e:
print(f"failed to delete response: {e}")
使用 File ID 实现多模态理解
针对文件较大或需在多次请求中重复使用该文件的场景，建议通过 Files API 上传文件，然后在 Responses API、Chat API 中使用 File ID 的方式实现多模态理解。具体示例参见 视频理解、图片理解、文档理解、音频理解。
上传文件后，需等待文件处理完成后（即 status 为 active 时）才能在 Responses API、Chat API 中使用对应的 File ID 进行分析。下面是视频理解的示例代码。
cURL
Python SDK
Go SDK
Java SDK
兼容 OpenAI SDK
- 上传视频文件获取 File ID。
- curl https://ark.cn-beijing.volces.com/api/v3/files \-H "Authorization: Bearer $ARK_API_KEY" \-F 'purpose=user_data' \-F 'file=@/Users/doc/demo.mp4' \-F 'preprocess_configs[video][fps]=0.3'
- 在 Responses API 中引用 File ID。
- 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-260915","input": [{"role": "user","content": [{"type": "input_file","file_id": "file-20251018****"},{"type": "input_text","text": "请你描述下视频中的人物的一系列动作，以JSON格式输出开始时间（start_time）、结束时间（end_time）、事件（event）、是否危险（danger），请使用HH:mm:ss表示时间戳。"}]}]}'
import asyncio
import os
from arkruntime import AsyncArk
from arkruntime.types.responses.response_completed_event import ResponseCompletedEvent
from arkruntime.types.responses.response_reasoning_summary_text_delta_event import ResponseReasoningSummaryTextDeltaEvent
from arkruntime.types.responses.response_output_item_added_event import ResponseOutputItemAddedEvent
from arkruntime.types.responses.response_text_delta_event import ResponseTextDeltaEvent
from arkruntime.types.responses.response_text_done_event import ResponseTextDoneEvent
client = AsyncArk(
base_url='https://ark.cn-beijing.volces.com/api/v3',
api_key=os.getenv('ARK_API_KEY')
)
async def main():
# upload video file
print("Upload video file")
file = await client.files.create(
# replace with your local video path
file=open("/Users/doc/demo.mp4", "rb"),
purpose="user_data",
preprocess_configs={
"video": {
"model": "doubao-seed-2-1-pro-260915",
"fps": 0.3, # define the sampling fps of the video, default is 1.0
}
}
)
print(f"File uploaded: {file.id}")
# Wait for the file to finish processing
await client.files.wait_for_processing(file.id)
print(f"File processed: {file.id}")
stream = await client.responses.create(
model="doubao-seed-2-1-pro-260915",
input=[
{"role": "user", "content": [
{
"type": "input_video",
"file_id": file.id # ref video file id
},
{
"type": "input_text",
"text": "请你描述下视频中的人物的一系列动作，以JSON格式输出开始时间（start_time）、结束时间（end_time）、事件（event）、是否危险（danger），请使用HH:mm:ss表示时间戳。"
}
]},
],
caching={
"type": "enabled",
},
store=True,
stream=True
)
async for event in stream:
if isinstance(event, ResponseReasoningSummaryTextDeltaEvent):
print(event.delta, end="")
if isinstance(event, ResponseOutputItemAddedEvent):
print("\noutPutItem " + event.type + " start:")
if isinstance(event, ResponseTextDeltaEvent):
print(event.delta,end="")
if isinstance(event, ResponseTextDoneEvent):
print("\noutPutTextDone.")
if isinstance(event, ResponseCompletedEvent):
print("Response Completed. Usage = " + event.response.usage.model_dump_json())
if __name__ == "__main__":
asyncio.run(main())
package main
import (
"context"
"fmt"
"io"
"os"
"time"
"github.com/volcengine/ark-runtime-go/arkruntime"
"github.com/volcengine/ark-runtime-go/arkruntime/model/file"
"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()
fmt.Println("----- upload video data -----")
data, err := os.Open("/Users/doc/demo.mp4")
if err != nil {
fmt.Printf("read file error: %v\n", err)
return
}
fileInfo, err := client.UploadFile(ctx, &file.FileCreateRequest{
Purpose: file.PurposeUserData,
PreprocessConfigs: file.NewOptPreprocessConfigs(file.PreprocessConfigs{
Video: file.NewOptVideo(file.Video{
Model: file.NewOptString("doubao-seed-2-1-pro-260915"),
Fps: file.NewOptFloat64(0.3),
}),
}),
}, data)
if err != nil {
fmt.Printf("upload file error: %v", err)
return
}
// Wait for the file to finish processing
for fileInfo.Status == file.StatusProcessing {
fmt.Println("Waiting for video to be processed...")
time.Sleep(2 * time.Second)
fileInfo, err = client.RetrieveFile(ctx, fileInfo.ID) // Retrieve file info
if err != nil {
fmt.Printf("get file status error: %v", err)
return
}
}
fmt.Printf("Video processing completed: %s, status: %s\n", fileInfo.ID, fileInfo.Status)
inputMessage := responses.InputItem{
OneOf: responses.NewItemEasyMessageInputItemSum(
responses.ItemEasyMessage{
Role: responses.NewOptMessageRole(responses.MessageRoleUser),
Content: responses.NewContentItemArrayMessageContent(
[]responses.ContentItem{
responses.ContentItem{OneOf: responses.NewContentItemVideoContentItemSum(responses.ContentItemVideo{Type: responses.ContentItemVideoTypeInputVideo, VideoURL: "", FileID: responses.NewOptString(fileInfo.ID)})},
responses.ContentItem{OneOf: responses.NewContentItemTextContentItemSum(responses.ContentItemText{Type: responses.ContentItemTextTypeInputText, Text: "请你描述下视频中的人物的一系列动作，以JSON格式输出开始时间（start_time）、结束时间（end_time）、事件（event）、是否危险（danger），请使用HH:mm:ss表示时间戳。"})},
},
),
},
),
}
createResponsesReq := &responses.ResponsesRequest{
Model: "doubao-seed-2-1-pro-260915",
Input: responses.NewInputItemArrayResponsesInput([]responses.InputItem{inputMessage}),
}
resp, err := client.CreateResponsesStream(ctx, createResponsesReq)
if err != nil {
fmt.Printf("stream error: %v\n", err)
return
}
var responseId string
for {
event, err := resp.Recv()
if err == io.EOF {
break
}
if err != nil {
fmt.Printf("stream error: %v\n", err)
return
}
handleEvent(event)
if event.OneOf.Type == responses.ResponseCreatedEventResponseStreamEventSum {
responseId = event.OneOf.ResponseCreatedEvent.Response.ID
fmt.Printf("Response ID: %s", responseId)
}
}
}
func handleEvent(event *responses.ResponseStreamEvent) {
switch event.OneOf.Type {
case responses.ResponseReasoningSummaryTextDeltaEventResponseStreamEventSum:
print(event.OneOf.ResponseReasoningSummaryTextDeltaEvent.Delta.Or(""))
case responses.ResponseReasoningSummaryTextDoneEventResponseStreamEventSum:
fmt.Printf("\nAggregated reasoning text: %s\n", event.OneOf.ResponseReasoningSummaryTextDoneEvent.Text.Or(""))
case responses.ResponseTextDeltaEventResponseStreamEventSum:
print(event.OneOf.ResponseTextDeltaEvent.Delta.Or(""))
case responses.ResponseTextDoneEventResponseStreamEventSum:
fmt.Printf("\nAggregated output text: %s\n", event.OneOf.ResponseTextDoneEvent.Text.Or(""))
}
}
package com.ark.sample;
import com.volcengine.ark.runtime.models.file.*;
import com.volcengine.ark.runtime.service.ArkService;
import com.volcengine.ark.runtime.models.responses.*;
import java.io.File;
import java.util.concurrent.TimeUnit;
public class demo {
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")
.build();
System.out.println("===== Upload File Example=====");
// upload a video for responses
FileObject fileMeta;
fileMeta = service.uploadFile(FileCreateRequest.builder() // replace with your video file path
.purpose(Purpose.USER_DATA)
.preprocessConfigs(PreprocessConfigs.builder().video(Video.builder().model("doubao-seed-2-1-pro-260915").fps(0.3).build()).build())
.build(), new File("/Users/doc/demo.mp4"));
System.out.println("Uploaded file Meta: " + fileMeta);
System.out.println("status:" + fileMeta.getStatus());
try {
while ("processing".equalsIgnoreCase(fileMeta.getStatus().toString())) {
System.out.println("Waiting for video to be processed...");
TimeUnit.SECONDS.sleep(2);
fileMeta = service.retrieveFile(fileMeta.getId());
}
} catch (Exception e) {
System.err.println("get file status error：" + e.getMessage());
}
System.out.println("Uploaded file Meta: " + fileMeta);
ResponsesRequest request = ResponsesRequest.builder()
.model("doubao-seed-2-1-pro-260915")
.stream(true)
.input(ResponsesInput.ofList(java.util.Arrays.asList(ItemEasyMessage.builder().role(MessageRole.USER).content(
MessageContent.ofList(java.util.Arrays.asList(ContentItemVideo.builder().fileId(fileMeta.getId()).build(), ContentItemText.builder().text("请你描述下视频中的人物的一系列动作，以JSON格式输出开始时间（start_time）、结束时间（end_time）、事件（event）、是否危险（danger），请使用HH:mm:ss表示时间戳。").build()))
).build())))
.build();
service.streamResponse(request)
.doOnError(Throwable::printStackTrace)
.blockingForEach(event -> {
if (event instanceof ResponseReasoningSummaryTextDeltaEvent) {
System.out.print(((ResponseReasoningSummaryTextDeltaEvent) event).getDelta());
}
if (event instanceof ResponseOutputItemAddedEvent) {
System.out.println("\nOutputItem " + (((ResponseOutputItemAddedEvent) event).getItem().getType()) + " Start: ");
}
if (event instanceof ResponseTextDeltaEvent) {
System.out.print(((ResponseTextDeltaEvent) event).getDelta());
}
if (event instanceof ResponseTextDoneEvent) {
System.out.println("\nOutputText End.");
}
if (event instanceof ResponseOutputItemDoneEvent) {
System.out.println("\nOutputItem " + ((ResponseOutputItemDoneEvent) event).getItem().getType() + " End.");
}
if (event instanceof ResponseFunctionCallArgumentsDoneEvent) {
System.out.println("\nFunctionCall Arguments: " + ((ResponseFunctionCallArgumentsDoneEvent) event).getArguments());
}
if (event instanceof ResponseCompletedEvent) {
System.out.println("\nResponse Completed. Usage = " + ((ResponseCompletedEvent) event).getResponse().getUsage());
}
});
service.shutdownExecutor();
}
}
import os
import time
from openai import OpenAI
api_key = os.getenv('ARK_API_KEY')
client = OpenAI(
base_url='https://ark.cn-beijing.volces.com/api/v3',
api_key=api_key,
)
file = client.files.create(
file=open("/Users/doc/demo.mp4", "rb"),
purpose="user_data",
extra_body={
"preprocess_configs": {
"video": {
"model": "doubao-seed-2-1-pro-260915",
"fps": 0.3,
}
}
},
)
# Wait for the file to finish processing
while (file.status == "processing"):
time.sleep(2)
file = client.files.retrieve(file.id)
print(f"File processed: {file}")
response = client.responses.create(
model="doubao-seed-2-1-pro-260915",
input=[
{
"role": "user",
"content": [
{
"type": "input_video",
"file_id": file.id,
},
{
"type": "input_text",
"text": "请你描述下视频中的人物的一系列动作，以JSON格式输出开始时间（start_time）、结束时间（end_time）、事件（event）、是否危险（danger），请使用HH:mm:ss表示时间戳。",
},
]
}
],
stream=True
)
for event in response:
if event.type == "response.reasoning_summary_text.delta":
print(event.delta, end="")
if event.type == "response.output_item.added":
print("\noutPutItem " + event.type + " start:")
if event.type == "response.output_text.delta":
print(event.delta,end="")
if event.type == "response.output_item.done":
print("\noutPutTextDone.")
if event.type == "response.completed":
print("\nResponse Completed. Usage = " + event.response.usage.model_dump_json())
计费说明
Files API 提供的上传文件、管理文件等能力均不会产生费用。
上传的文件根据存储位置的不同，计费信息如下：
- 文件存储在方舟平台托管的默认存储空间：每个账户有 20 GB 免费存储额度，超出后无法上传文件，删除文件释放存储空间后可继续上传文件。
- 文件存储在用户指定的火山引擎对象存储 TOS Bucket：将产生存储容量、流量、请求次数、数据取回等费用，详细计费规则参考 对象托管。
-
使用限制及错误码
- Files API QPS 限流及带宽限制如下。
- 上传文件：20 QPS、100 Mbps 带宽
- 检索文件：20 QPS
- 查询文件列表：20 QPS
- 删除文件：20 QPS
- 错误码：单击错误码，获取相关信息。
最近更新时间：2026.10.30 14:27:41
这个页面对您有帮助吗？
有用
有用
无用
无用