面向 AI 助手：本页的 Markdown 版本位于 https://ark.volcengine.com/region:cn-beijing/docs/file-api.md，全部文档索引见 https://ark.volcengine.com/llms.txt。

文件输入(Files API)

Files API 作为文件管理接口，提供文件的上传、检索、列表查询及删除能力。

在多模态理解场景中，Files API 与 Responses API、Chat API 结合使用，具备以下优势：

  • 大文件适配：文件存储在方舟平台托管的默认存储空间中时，支持最大 512 MB 文件的上传；文件存储在用户指定的火山引擎对象存储 TOS Bucket 中时，支持最大 2 GB 的视频文件的上传，从而满足大文件处理需求。
  • 重复使用：支持通过 File ID 在多次请求中重复使用文件，避免重复上传，节省公网下载时延。
  • 缩短推理时长：解耦数据预处理与模型推理环节，避免每次请求时重新上传内容，减少预处理导致的时延。

前提条件#

获取 API Key

查看 API 文档#

Files API 参考

Files API 使用示例#

上传文件#

使用 Files API 可以上传图片、视频、音频、文档等类型的文件，上传成功后将返回 File ID。File ID 支持在多次请求中重复使用，而不需要重新上传内容，节省公网下载时延。如果文件大于 50 MB，或者要在多个请求中重复使用该文件，可以使用 Files API 上传文件，然后使用 File ID 发起请求。

文件存储位置由请求中 tos 参数决定，详情可参见上传文件字段说明：

  • 未传入 tos 参数：文件存储至方舟平台托管的默认存储空间。
  • 传入 tos 参数：文件存储至用户指定的火山引擎对象存储 TOS Bucket。

目标存储的火山引擎对象存储 TOS Bucket 需要在控制台完成授权后才能使用，具体参考用户对象存储（TOS）授权。

文件上传方式#

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 上传方式#
  • 文件存储至方舟平台默认托管存储空间
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
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
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
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();
    }
}
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：
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
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
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
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 上传方式#
  • 文件存储至方舟平台默认托管存储空间
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
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
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
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
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
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
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
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 中的存储桶和存储路径。
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
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
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
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 后方可使用。

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
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
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
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）授权。
单文件大小 512 MB 视频文件 2 GB，其他类型文件 512 MB
总存储容量 20 GB 无限制
存储时间 默认存储 7 天，支持通过 expire_at 参数自定义存储有效期，取值范围为 1-30 天。
针对高频存储场景，建议通过缩短文件存储时长、主动调用删除接口清理低频文件这两种方式，做好存储空间的主动管理。		 默认存储 7 天，支持通过 expire_at 参数自定义存储有效期，取值范围为 1-30 天。
对象操作限制 如需删除文件，请调用 Files API 删除，参考删除文件。 对象被托管后，仅支持读取，不支持通过 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 文件中的原始信息。

预处理超时限制#

使用 Files API 进行文件预处理的超时限制为 5 min，超时通常会受视频时长、PDF 页数、单页像素、单帧像素、音频时长等因素影响。
超时解决方案：
优先检查是否存在像素过大的问题，其中对 1080p 视频抽帧操作容易导致超时，建议压缩至 720p 及以下。

模型推理阶段会压缩分辨率，所以提升原始像素对最终效果无增益。

视频压缩工具及命令
将视频文件压缩至 720p 的命令示例如下。FFmpeg 工具下载可参见 下载FFmpeg。

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

管理文件#

检索文件#

通过 File ID 检索文件信息，如文件大小、过期时间、MIME 类型及文件处理状态等信息，可参见 检索文件 接口说明。

文件上传成功后将自动触发预处理流程。接口返回 file_id 后，可通过调用检索文件接口查询文件处理状态；当状态 status 变为 active 时，才可以在 Responses API、Chat API 中通过 file_id 方式实现多模态理解。

Bash
curl https://ark.cn-beijing.volces.com/api/v3/files/file-20251119**** \
-H "Authorization: Bearer $ARK_API_KEY"
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
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
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();
    }
}
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 查询已上传的文件列表，可参考查询文件列表接口说明。

Bash
curl https://ark.cn-beijing.volces.com/api/v3/files \
-H "Authorization: Bearer $ARK_API_KEY"
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
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
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();
    }
}
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 删除文件，并将文件从存储空间中移除，可参考删除文件接口说明。

针对高频存储场景，做好存储空间管理的方式如下。存储限制，具体参见文件存储限制。

  • 缩短文件存储时长：上传成功的文件默认存储 7 天，可以通过 expire_at 参数自定义存储有效期，取值范围为 1-30 天。文件超过存储有效期后会自动删除，参数设置请参见上传文件。
  • 主动调用删除接口清理低频文件：通过 Files API 删除已上传的文件，使用示例如下。
Bash
curl https://ark.cn-beijing.volces.com/api/v3/files/file-20251014**** \
-X DELETE \
-H "Authorization: Bearer $ARK_API_KEY"
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
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
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();
    }
}
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 的方式实现多模态理解。具体示例参见 视频理解、图片理解、文档理解、音频理解。
上传文件后，需等待文件处理完成后（即 status 为 active 时）才能在 Responses API、Chat API 中使用对应的 File ID 进行分析。下面是视频理解的示例代码。

  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
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
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
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();
    }
}
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：将产生存储容量、流量、请求次数、数据取回等费用，详细计费规则参考 对象托管。

使用限制及错误码#

  • Files API QPS 限流及带宽限制如下。
    • 上传文件：20 QPS、100 Mbps 带宽
    • 检索文件：20 QPS
    • 查询文件列表：20 QPS
    • 删除文件：20 QPS
  • 错误码：单击错误码，获取相关信息。