# 文件输入(Files API) > 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。 Files API 作为文件管理接口，提供文件的上传、检索、列表查询及删除能力。 在多模态理解场景中，Files API 与 Responses API、Chat API 结合使用，具备以下优势： - 大文件适配：文件存储在方舟平台托管的默认存储空间中时，支持最大 512 MB 文件的上传；文件存储在用户指定的火山引擎对象存储 TOS Bucket 中时，支持最大 2 GB 的视频文件的上传，从而满足大文件处理需求。 - 重复使用：支持通过 File ID 在多次请求中重复使用文件，避免重复上传，节省公网下载时延。 - 缩短推理时长：解耦数据预处理与模型推理环节，避免每次请求时重新上传内容，减少预处理导致的时延。 # 前提条件 [获取 API Key](https://ark.volcengine.com/region:cn-beijing/apiKey) # 查看 API 文档 [Files API 参考](/docs/upload-files-api) # Files API 使用示例 ## 上传文件 使用 Files API 可以上传图片、视频、音频、文档等类型的文件，上传成功后将返回 File ID。File ID 支持在多次请求中重复使用，而不需要重新上传内容，节省公网下载时延。如果文件大于 50 MB，或者要在多个请求中重复使用该文件，可以使用 Files API 上传文件，然后使用 File ID 发起请求。 文件存储位置由请求中 `tos` 参数决定，详情可参见[上传文件](/docs/upload-files-api)字段说明： * 未传入 `tos` 参数：文件存储至方舟平台托管的默认存储空间。 * 传入 `tos` 参数：文件存储至用户指定的火山引擎对象存储 TOS Bucket。 > 目标存储的火山引擎对象存储 TOS Bucket 需要在控制台完成授权后才能使用，具体参考[用户对象存储（TOS）授权](/docs/project-configuration#4eb1b277)。 > > ### 文件上传方式 Files API 支持二进制文件、文件 URL 两种方式上传文件。 * `file`（二进制文件）：要上传的本地文件。文件可存储至方舟平台默认托管存储空间，或用户指定的火山引擎 TOS 存储桶。 * `url`（文件 URL）：支持 HTTP/HTTPS URL、TOS URI 两种方式。 * HTTP/HTTPS URL：公网可直接访问的文件 URL，请确保文件 URL 可被访问。文件可存储至方舟平台默认托管存储空间，或用户指定的火山引擎 TOS 存储桶。 * TOS URI：对象存储 TOS 专属的资源定位标识，格式为 `tos:////`。使用该方式时，文件仅支持存储至火山引擎 TOS 存储桶。 #### file 上传方式 - 文件存储至方舟平台默认托管存储空间 **选项：Curl** ```Bash 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' ``` 响应参数如下： ```Bash { "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 } } } ``` **选项：Python SDK** ```Python 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( # replace with your local video path file=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) ``` **选项：Go SDK** ```Go 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() data, err := os.Open("/Users/doc/demo.mp4") if err != nil { fmt.Printf("read file error: %v ", 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 ", fileInfo) } ``` **选项：Java SDK** ```Java 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(); } } ``` **选项：兼容 OpenAI SDK** ```Python 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') ) file = client.files.create( # replace with your local video path file=open("/Users/doc/demo.mp4", "rb"), purpose="user_data", extra_body={ "preprocess_configs":{ "video": { "fps": 0.3 } } } ) print(file) ``` - 文件存储至火山引擎对象存储 TOS Bucket： **选项：Curl** ```Bash 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' \ -F "tos[bucket]=my-bucket" \ -F "tos[prefix]=ark-files/" ``` **选项：Python SDK** ```Python 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( 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) ``` **选项：Go SDK** ```Go 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() data, err := os.Open("/Users/doc/demo.mp4") if err != nil { fmt.Printf("read file error: %v ", 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 ", fileInfo) } ``` **选项：Java SDK** ```Java 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 上传方式 - 文件存储至方舟平台默认托管存储空间 **选项：Curl** ```Bash curl -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" ``` **选项：Python SDK** ```Python 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( purpose="user_data", url="https://example.com/docs/demo_img.png" ) print(file) ``` **选项：Go SDK** ```Go 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("https://example.com/docs/demo_img.png"), }, nil) if err != nil { fmt.Printf("upload file error: %v", err) return } fmt.Printf("file info: %v ", fileInfo) } ``` **选项：Java SDK** ```Java 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 **选项：Curl** ```Bash curl -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/" ``` **选项：Python SDK** ```Python 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="https://example.com/docs/demo_img.png", purpose="user_data", tos={ "bucket": "my-bucket", "prefix": "ark-files/" } ) print(file) ``` **选项：Go SDK** ```Go 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("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 ", fileInfo) } ``` **选项：Java SDK** ```Java 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 中的存储桶和存储路径。 **选项：Curl** ```Bash 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/" ``` **选项：Python SDK** ```Python 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) ``` **选项：Go SDK** ```Go 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 ", fileInfo) } ``` **选项：Java SDK** ```Java 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** ```Bash 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" ``` **选项：Python SDK** ```Python 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) ``` **选项：Go SDK** ```Go 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 ", fileInfo) } ``` **选项：Java SDK** ```Java 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 | |---|---|---| |授权要求 |无需额外授权。 |目标存储 Bucket 需要在控制台完成授权后才能使用，参考[用户对象存储（TOS）授权](/docs/project-configuration#4eb1b277)。 | \ | | | | |单文件大小 |512 MB |视频文件 2 GB，其他类型文件 512 MB | |总存储容量 |20 GB |无限制 | | 存储时间 | 默认存储 7 天，支持通过 **expire_at** 参数自定义存储有效期，取值范围为 1-30 天。 | 默认存储 7 天，支持通过 **expire_at** 参数自定义存储有效期，取值范围为 1-30 天。 | \ | |> 针对高频存储场景，建议通过缩短文件存储时长、主动调用删除接口清理低频文件这两种方式，做好存储空间的主动管理。 | | |对象操作限制 |如需删除文件，请调用 Files API 删除，参考[删除文件](/docs/delete-files-api)。 |对象被托管后，仅支持读取，不支持通过 TOS 控制台或 TOS API 删除、覆盖或修改对象。命中该对象的生命周期删除、覆盖式复制等异步写、删、改操作，同样受到托管保护限制。如需删除文件，请调用 Files API 删除。参考[删除文件](/docs/delete-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 及以下。 > 模型推理阶段会压缩分辨率，所以提升原始像素对最终效果无增益。 **视频压缩工具及命令** 将视频文件压缩至 720p 的命令示例如下。FFmpeg 工具下载可参见 [下载FFmpeg](https://ffmpeg.org/download.html)。 ```Bash 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 类型 | |---|---|---| |图片 |.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` | > **说明** > > 常见问题及解决方案参见[支持 TS 格式的视频文件吗？](/docs/modelark-faq#85251eec) ## 管理文件 ### 检索文件 通过 File ID 检索文件信息，如文件大小、过期时间、MIME 类型及文件处理状态等信息，可参见 [检索文件](/docs/search-files-api) 接口说明。 > 文件上传成功后将自动触发预处理流程。接口返回 `file_id` 后，可通过调用检索文件接口查询文件处理状态；当状态 `status` 变为 `active` 时，才可以在 Responses API、Chat API 中通过 `file_id` 方式实现多模态理解。 **选项：Curl** ```Bash curl https://ark.cn-beijing.volces.com/api/v3/files/file-20251119**** \ -H "Authorization: Bearer $ARK_API_KEY" ``` **选项：Python SDK** ```Python 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) ``` **选项：Go SDK** ```Go 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) } ``` **选项：Java SDK** ```Java 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(); } } ``` **选项：兼容 OpenAI SDK** ```Python 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) ``` ### 查询文件列表 通过 Files API 查询已上传的文件列表，可参考[查询文件列表](/docs/list-files-api)接口说明。 **选项：Curl** ```Bash curl https://ark.cn-beijing.volces.com/api/v3/files \ -H "Authorization: Bearer $ARK_API_KEY" ``` **选项：Python SDK** ```Python 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) ``` **选项：Go SDK** ```Go 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) } ``` **选项：Java SDK** ```Java 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(); } } ``` **选项：兼容 OpenAI SDK** ```Python 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) ``` ### 删除文件 删除文件接口用于根据文件 ID 删除文件，并将文件从存储空间中移除，可参考[删除文件](/docs/delete-files-api)接口说明。 针对高频存储场景，做好存储空间管理的方式如下。存储限制，具体参见[文件存储限制](/docs/file-api#d75377d6)。 * 缩短文件存储时长：上传成功的文件默认存储 7 天，可以通过 **expire_at** 参数自定义存储有效期，取值范围为 1-30 天。文件超过存储有效期后会自动删除，参数设置请参见[上传文件](/docs/upload-files-api)。 * 主动调用删除接口清理低频文件：通过 Files API 删除已上传的文件，使用示例如下。 **选项：Curl** ```Bash curl https://ark.cn-beijing.volces.com/api/v3/files/file-20251014**** \ -X DELETE \ -H "Authorization: Bearer $ARK_API_KEY" ``` **选项：Python SDK** ```Python 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}") ``` **选项：Go SDK** ```Go 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) } ``` **选项：Java SDK** ```Java 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(); } } ``` **选项：兼容 OpenAI SDK** ```Python 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 的方式实现多模态理解。具体示例参见 [视频理解](/docs/multimodal-understanding#098ef3d4)、[图片理解](/docs/multimodal-understanding#70e09284)、[文档理解](/docs/multimodal-understanding#18a762a5)、[音频理解](/docs/audio-understanding)。 上传文件后，需等待文件处理完成后（即 **status** 为 active 时）才能在 Responses API、Chat API 中使用对应的 File ID 进行分析。下面是视频理解的示例代码。 **选项：cURL** 1. 上传视频文件获取 File ID。 ```Bash 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' ``` 2. 在 Responses API 中引用 File ID。 ```Bash 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表示时间戳。" } ] } ] }' ``` **选项：Python SDK** ```Python 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()) ``` **选项：Go SDK** ```Go 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("")) } } ``` **选项：Java SDK** ```Java 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(); } } ``` **选项：兼容 OpenAI SDK** ```Python 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：将产生存储容量、流量、请求次数、数据取回等费用，详细计费规则参考 [对象托管](https://docs.volcengine.com/docs/6349/2532373?lang=zh#Mv2UN2Bn)。 # 使用限制及错误码 * Files API QPS 限流及带宽限制如下。 * 上传文件：20 QPS、100 Mbps 带宽 * 检索文件：20 QPS * 查询文件列表：20 QPS * 删除文件：20 QPS * 错误码：单击[错误码](/docs/error-codes)，获取相关信息。