# 上传文件
> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。
`POST https://ark.cn-beijing.volces.com/api/v3/files`
上传文件到方舟平台，供后续模型调用作为输入（如图像、视频、文档等）。文件在一定时间后过期删除。
## 鉴权
本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。
* API Key 鉴权，请在 [API Key 管理](https://ark.volcengine.com/region:cn-beijing/apiKey) 页面，获取长效 API Key。
---
## 请求参数
### Body 参数
**file** `object` `必选` | 上传的文件
需要上传的文件，要求为二进制文件。具体限制请参见 Files API 教程
> **说明：注意**
>
> 文件上传支持二进制文件和文件 URL 两种传入方式，`file`、`url` 为二选一必填参数，不可同时传参。
**purpose** `string` `必选` | 文件用途
文件用途。
- `user_data`：可以灵活使用的文件，能够用于任意用途。
- `agent`：智能体（Agent）场景使用的文件。
**url** `string` | 文件 URL
文件 URL，支持以下两种 URL 类型：
- HTTP/HTTPS URL：公网可直接访问的文件 URL，请确保文件 URL 可被访问。
- TOS URI：对象存储 TOS 专属的资源定位标识，格式为 `tos:////`。其中，``、`` 和 `` 分别表示存储桶名称、存储路径和文件名。详细使用说明可参考 [TOS URI 上传方式](/docs/file-api#tos-uri-upload) 部分，也可前往 [火山引擎对象存储 TOS Bucket](https://console.volcengine.com/tos/bucket?projectName=default) 中管理存储桶。
> **说明：注意**
>
> - 文件上传支持二进制文件和文件 URL 两种传入方式，`file`、`url` 为二选一必填参数，不可同时传参。
>
> - 传入 TOS URI 时，必须将文件存储到火山引擎对象存储 TOS Bucket 中，此时 `tos.bucket`、`tos.prefix` 为必填参数。
**tos** `object` | TOS 存储配置
文件存储的 TOS 信息。TOS 即火山引擎对象存储服务；配置本参数后，上传文件将存储至用户指定的火山引擎对象存储 TOS Bucket 中，不再存入方舟平台默认托管存储空间。
> **说明**
>
> - 不传 `tos` 参数：文件存储在方舟平台托管的默认存储空间，单文件不超过 512 MB。已存入方舟平台托管存储的历史文件，不会自动迁移至其他存储位置。
>
> - 传 `tos` 参数：文件存储在用户指定的火山引擎对象存储 TOS Bucket 中，视频文件不超过 2 GB，其他类型文件不超过 512 MB，支持格式详见 [文件类型](/docs/file-api#81920512)。授权写入用户指定 TOS Bucket 中的文件，不支持在 TOS 侧删除或修改；如需删除文件，可调用 Files API 删除，参考 [删除文件](/docs/delete-files-api)。
**bucket** `string` | 存储桶名称
`tos.bucket`
目标文件待写入的 TOS 存储桶名称，该存储桶需提前完成创建，参考 [创建存储桶](https://docs.volcengine.com/docs/6349/75024?lang=zh)。
**prefix** `string` | 存储路径前缀
`tos.prefix`
文件在目标 TOS 存储桶内的存放前缀路径，入参填写相对路径格式，上传后文件将落地至该前缀目录下。示例：`arkfiles/`。
**preprocess_configs** `object` | 预处理配置
用于设置不同文件类型的预处理规则。
**video** `object` | 视频预处理配置
`preprocess_configs.video`
视频预处理相关配置。
> **说明**
>
> 配置 `model` 字段后，系统将根据对应模型的抽帧策略，自动填充 `max_video_tokens`、`min_frame_tokens`、`max_frame_tokens`、`min_frames` 四个字段的默认值，具体取值参考 [模型抽帧策略说明](/docs/video-understanding#203baa92)。
**fps** `number` `默认值 1` | 抽帧帧率
`preprocess_configs.video.fps`
每秒钟从视频中抽取指定数量的图像。取值越高，对于视频中画面变化理解越精细；取值越低，对于视频中画面变化感知减弱，但是使用的 token 花费少，速度也更快。
> **说明：注意**
>
> 取值范围：`[0.2, 5]`。单视频 token 用量范围在 `[10k, 80k]`。
**取值范围**：`[0.2, 5]`
**model** `string` | 预处理模型
`preprocess_configs.video.model`
使用该文件进行推理时，要使用的视频理解模型 ID（Model ID）或 Endpoint ID。
> **说明**
>
> Files API 中设置的模型 ID 与推理使用的模型 ID 不强耦合，只影响上传视频文件时预处理抽帧策略。关于预处理抽帧策略，参见 [抽帧策略](/docs/video-understanding#203baa92)。
>
> - 传入模型 ID：传入不同的模型 ID 会采用不同的抽帧策略。
> - 传入 Endpoint ID：会按照上传时 Endpoint ID 映射的模型对应的抽帧策略进行抽帧。
> - 不传该参数时：默认采用 `doubao-seed-1.8` 之前的模型对应的抽帧策略。
> **说明：注意**
>
> 如需处理视频中的音频内容，该字段需指定为支持音频理解的模型，具体支持的模型可参见 [模型列表](/docs/model-list#9619c0ba)。
**max_video_tokens** `integer` | 视频最大 tokens 数
`preprocess_configs.video.max_video_tokens`
视频最大 tokens 数，值越大保留的视频信息越多。
**取值范围**：`[10240, 204800]`
**min_frame_tokens** `integer` | 单帧最小 tokens 数
`preprocess_configs.video.min_frame_tokens`
单帧最小 tokens 数，用于控制单帧压缩的下限。值越小，允许对单帧进行更大的压缩，但单帧细节下降。
**取值范围**：`[16, 128]`
**max_frame_tokens** `integer` | 单帧最大 tokens 数
`preprocess_configs.video.max_frame_tokens`
单帧最大 tokens 数，用于控制单帧质量的上限。值越大，允许对单帧保留更多的细节。
**取值范围**：`[128, 640]`
**min_frames** `integer` | 最小抽帧数
`preprocess_configs.video.min_frames`
最小抽帧数，用于保证短视频具备足够的处理帧数。若 `fps` 字段抽帧总数小于 `min_frames`，则优先按照 `min_frames` 配置要求抽帧。
**取值范围**：`[5, 16]`
**expire_at** `integer` | 文件过期时间
设置存储的有效期，需要传入 UTC Unix 时间戳（单位：秒）。最少保留 1 天，最多保留 30 天；不传时默认保留 7 天（当前时刻 + 604800）
> **说明：注意**
>
> 取值范围：`[当前时刻+86400, 当前时刻+2592000]`，即最少保留 1 天，最多保留 30 天。不传时默认保留 7 天（当前时刻 + 604800）。
## 响应参数
**object** `string` | 对象类型
对象类型，固定为 `file`。
**id** `string` | 文件 ID
文件的唯一标识符。
**purpose** `string` | 文件用途
文件用途。
- `user_data`：可以灵活使用的文件，能够用于任意用途。
- `agent`：智能体（Agent）场景使用的文件。
**scope** `object` | 文件所属作用域信息
文件所属作用域信息，用于标识该文件创建时归属的会话上下文。
**type** `string` | 作用域类型
`scope.type`
作用域类型，当前固定取值为 `session`。
**id** `string` | 作用域 ID
`scope.id`
作用域 ID，返回对应的会话 ID。
**filename** `string` | 文件名
**tos** `object` | 文件存储的 TOS 信息
文件存储的 TOS 信息。TOS 即火山引擎对象存储服务，仅当用户传入 `tos` 参数时才会返回。
**bucket** `string` | 目标文件待写入的 TOS 存储桶名称
`tos.bucket`
**object_key** `string` | 文件存储在 TOS 中的路径信息
`tos.object_key`
**bytes** `integer` | 文件大小
文件大小，以 bytes 为单位。
**created_at** `integer` | 创建时间
本次请求上传文件时的 Unix 时间戳（秒）。
**expire_at** `integer` | 过期时间
文件过期时间的 Unix 时间戳（秒）。
**mime_type** `string` | MIME 类型
文件的 MIME 类型，如 `application/pdf`。
**status** `string` | 文件处理状态
文件处理状态。
- `processing`：文件正在预处理，无法使用。
- `active`：文件已处理完成，可以使用。
- `failed`：文件上传失败，错误详情查看 `error` 字段。
**error** `object` | 错误信息
文件上传失败时返回的错误对象，即 `status` 取值为 `failed` 时才会返回该字段。
**code** `string` | 错误码
`error.code`
**message** `string` | 错误描述信息
`error.message`
**preprocess_configs** `object` | 预处理配置
用于设置不同文件类型的预处理规则。
**video** `object` | 视频预处理配置
`preprocess_configs.video`
视频预处理相关配置。
**fps** `number` | 抽帧帧率
`preprocess_configs.video.fps`
每秒钟从视频中抽取指定数量的图像。取值越高，对于视频中画面变化理解越精细；取值越低，对于视频中画面变化感知减弱，但是使用的 token 花费少，速度也更快。
> **说明：注意**
>
> 取值范围：`[0.2, 5]`。单视频 token 用量范围在 `[10k, 80k]`。
**取值范围**：`[0.2, 5]`
**model** `string` | 预处理模型
`preprocess_configs.video.model`
使用该文件进行推理时，要使用的视频理解模型 ID（Model ID）或 Endpoint ID。
> **说明**
>
> Files API 中设置的模型 ID 与推理使用的模型 ID 不强耦合，只影响上传视频文件时预处理抽帧策略。关于预处理抽帧策略，参见 [抽帧策略](/docs/video-understanding#203baa92)。
>
> - 传入模型 ID：传入不同的模型 ID 会采用不同的抽帧策略。
> - 传入 Endpoint ID：会按照上传时 Endpoint ID 映射的模型对应的抽帧策略进行抽帧。
> - 不传该参数时：默认采用 `doubao-seed-1.8` 之前的模型对应的抽帧策略。
> **说明：注意**
>
> 如需处理视频中的音频内容，该字段需指定为支持音频理解的模型，具体支持的模型可参见 [模型列表](/docs/model-list#9619c0ba)。
**max_video_tokens** `integer` | 视频最大 tokens 数
`preprocess_configs.video.max_video_tokens`
视频最大 tokens 数，值越大保留的视频信息越多。
**取值范围**：`[10240, 204800]`
**min_frame_tokens** `integer` | 单帧最小 tokens 数
`preprocess_configs.video.min_frame_tokens`
单帧最小 tokens 数，用于控制单帧压缩的下限。值越小，允许对单帧进行更大的压缩，但单帧细节下降。
**取值范围**：`[16, 128]`
**max_frame_tokens** `integer` | 单帧最大 tokens 数
`preprocess_configs.video.max_frame_tokens`
单帧最大 tokens 数，用于控制单帧质量的上限。值越大，允许对单帧保留更多的细节。
**取值范围**：`[128, 640]`
**min_frames** `integer` | 最小抽帧数
`preprocess_configs.video.min_frames`
最小抽帧数，用于保证短视频具备足够的处理帧数。若 `fps` 字段抽帧总数小于 `min_frames`，则优先按照 `min_frames` 配置要求抽帧。
**取值范围**：`[5, 16]`
## 代码示例
## 文件上传
### cURL
#### Request
```bash
curl https://ark.cn-beijing.volces.com/api/v3/files \
-H "Authorization: Bearer $ARK_API_KEY" \
-F 'purpose=user_data' \
-F 'file=@/root/projects/ark/ark_video.mp4' \
-F 'preprocess_configs[video][fps]=0.3'
```
#### Response
```
{
"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
#### Request
```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("/root/projects/ark/ark_video.mp4", "rb"),
purpose="user_data",
preprocess_configs={
"video": {
"fps": 0.3, # define the sampling fps of the video, default is 1.0
}
}
)
print(file)
```
#### Response
```
{
"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
}
}
}
```
### Go
#### Request
```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("/root/projects/ark/ark_video.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)
}
```
#### Response
```
{
"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
}
}
}
```
### Java
#### Request
```java
package com.ark.example;
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() // replace with your image file path
.purpose(Purpose.USER_DATA)
.preprocessConfigs(PreprocessConfigs.builder().video(Video.builder().fps(0.3).build()).build())
.build(), new File("/root/projects/ark/ark_video.mp4"));
System.out.println("Uploaded file Meta: " + fileMeta);
service.shutdownExecutor();
}
}
```
#### Response
```
{
"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-OpenAI
#### Request
```python
import asyncio
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("/root/projects/ark/ark_video.mp4", "rb"),
purpose="user_data",
extra_body={
"preprocess_configs":{
"video": {
"fps": 0.3
}
}
}
)
print(file)
```
#### Response
```
{
"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
}
}
}
```
## URL 上传（HTTPS URL）
### cURL
#### Request
```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/"
```
#### Response
```
{
"object": "file",
"id": "file-20260529151145-hbh6r",
"purpose": "user_data",
"filename": "demo_img.png",
"bytes": 84669,
"mime_type": "image/png",
"created_at": 1780038705,
"expire_at": 1780643505,
"status": "active",
"tos": {
"bucket": "my-bucket",
"object_key": "ark-files/ark_processed/file-20260529151145-hbh6r/Image/demo_img.png"
}
}
```
### Python
#### Request
```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)
```
#### Response
```
{
"object": "file",
"id": "file-20260529151145-hbh6r",
"purpose": "user_data",
"filename": "demo_img.png",
"bytes": 84669,
"mime_type": "image/png",
"created_at": 1780038705,
"expire_at": 1780643505,
"status": "active",
"tos": {
"bucket": "my-bucket",
"object_key": "ark-files/ark_processed/file-20260529151145-hbh6r/Image/demo_img.png"
}
}
```
### Go
#### Request
```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\n", fileInfo)
}
```
#### Response
```
{
"object": "file",
"id": "file-20260529151145-hbh6r",
"purpose": "user_data",
"filename": "demo_img.png",
"bytes": 84669,
"mime_type": "image/png",
"created_at": 1780038705,
"expire_at": 1780643505,
"status": "active",
"tos": {
"bucket": "my-bucket",
"object_key": "ark-files/ark_processed/file-20260529151145-hbh6r/Image/demo_img.png"
}
}
```
### Java
#### Request
```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;
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);
service.shutdownExecutor();
}
}
```
#### Response
```
{
"object": "file",
"id": "file-20260529151145-hbh6r",
"purpose": "user_data",
"filename": "demo_img.png",
"bytes": 84669,
"mime_type": "image/png",
"created_at": 1780038705,
"expire_at": 1780643505,
"status": "active",
"tos": {
"bucket": "my-bucket",
"object_key": "ark-files/ark_processed/file-20260529151145-hbh6r/Image/demo_img.png"
}
}
```
## URL 上传（TOS URI）
### cURL
#### Request
```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/"
```
#### Response
```
{
"object": "file",
"id": "file-20260529151702-wt2cd",
"purpose": "user_data",
"filename": "raw_video.mp4",
"bytes": 11041468,
"mime_type": "video/mp4",
"created_at": 1780039022,
"expire_at": 1780643822,
"status": "processing",
"tos": {
"bucket": "my-bucket",
"object_key": "ark-files/ark_processed/file-20260529151702-wt2cd/Video/raw_video.mp4"
}
}
```
### Python
#### Request
```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)
```
#### Response
```
{
"object": "file",
"id": "file-20260529151702-wt2cd",
"purpose": "user_data",
"filename": "raw_video.mp4",
"bytes": 11041468,
"mime_type": "video/mp4",
"created_at": 1780039022,
"expire_at": 1780643822,
"status": "processing",
"tos": {
"bucket": "my-bucket",
"object_key": "ark-files/ark_processed/file-20260529151702-wt2cd/Video/raw_video.mp4"
}
}
```
### Go
#### Request
```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\n", fileInfo)
}
```
#### Response
```
{
"object": "file",
"id": "file-20260529151702-wt2cd",
"purpose": "user_data",
"filename": "raw_video.mp4",
"bytes": 11041468,
"mime_type": "video/mp4",
"created_at": 1780039022,
"expire_at": 1780643822,
"status": "processing",
"tos": {
"bucket": "my-bucket",
"object_key": "ark-files/ark_processed/file-20260529151702-wt2cd/Video/raw_video.mp4"
}
}
```
### Java
#### Request
```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;
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);
service.shutdownExecutor();
}
}
```
#### Response
```
{
"object": "file",
"id": "file-20260529151702-wt2cd",
"purpose": "user_data",
"filename": "raw_video.mp4",
"bytes": 11041468,
"mime_type": "video/mp4",
"created_at": 1780039022,
"expire_at": 1780643822,
"status": "processing",
"tos": {
"bucket": "my-bucket",
"object_key": "ark-files/ark_processed/file-20260529151702-wt2cd/Video/raw_video.mp4"
}
}
```
## 大视频文件上传
### cURL
#### Request
```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"
```
#### Response
```
{
"object": "file",
"id": "file-20260529151956-v6xd7",
"purpose": "user_data",
"filename": "long-video.mp4",
"bytes": 11041468,
"mime_type": "video/mp4",
"created_at": 1780039196,
"expire_at": 1780643996,
"status": "processing",
"preprocess_configs": {
"video": {
"fps": 1,
"max_video_tokens": 200000,
"min_frames": 16
}
},
"tos": {
"bucket": "my-bucket",
"object_key": "ark-files/ark_processed/file-20260529151956-v6xd7/Video/long-video.mp4"
}
}
```
### Python
#### Request
```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)
```
#### Response
```
{
"object": "file",
"id": "file-20260529151956-v6xd7",
"purpose": "user_data",
"filename": "long-video.mp4",
"bytes": 11041468,
"mime_type": "video/mp4",
"created_at": 1780039196,
"expire_at": 1780643996,
"status": "processing",
"preprocess_configs": {
"video": {
"fps": 1,
"max_video_tokens": 200000,
"min_frames": 16
}
},
"tos": {
"bucket": "my-bucket",
"object_key": "ark-files/ark_processed/file-20260529151956-v6xd7/Video/long-video.mp4"
}
}
```
### Go
#### Request
```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\n", fileInfo)
}
```
#### Response
```
{
"object": "file",
"id": "file-20260529151956-v6xd7",
"purpose": "user_data",
"filename": "long-video.mp4",
"bytes": 11041468,
"mime_type": "video/mp4",
"created_at": 1780039196,
"expire_at": 1780643996,
"status": "processing",
"preprocess_configs": {
"video": {
"fps": 1,
"max_video_tokens": 200000,
"min_frames": 16
}
},
"tos": {
"bucket": "my-bucket",
"object_key": "ark-files/ark_processed/file-20260529151956-v6xd7/Video/long-video.mp4"
}
}
```
### Java
#### Request
```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();
}
}
```
#### Response
```
{
"object": "file",
"id": "file-20260529151956-v6xd7",
"purpose": "user_data",
"filename": "long-video.mp4",
"bytes": 11041468,
"mime_type": "video/mp4",
"created_at": 1780039196,
"expire_at": 1780643996,
"status": "processing",
"preprocess_configs": {
"video": {
"fps": 1,
"max_video_tokens": 200000,
"min_frames": 16
}
},
"tos": {
"bucket": "my-bucket",
"object_key": "ark-files/ark_processed/file-20260529151956-v6xd7/Video/long-video.mp4"
}
}
```