# 查询文件列表

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

`GET 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。

---

<span id="request-parameters"></span>
## 请求参数

### Query 参数

> 在 URL Query String 中传入。

**after** `string` | 分页游标

游标参数，返回该文件 ID 之后的文件，用于分页拉取下一页数据。通常传入上一页响应中的 `last_id`

**limit** `integer` `默认值 100` | 单次返回数量

控制单次返回的最大文件数。

> **说明：注意**
>
> 取值范围：1~100。

**order** `string` `默认值 desc` | 排序方式

按照文件 `created_at` 的时间戳顺序，控制文件的排序方式：
* `asc`：正序排列；
* `desc`：倒序排列。

**purpose** `string` | 文件用途筛选

按文件用途进行筛选，仅返回具有指定用途的文件。

- `user_data`：可以灵活使用的文件，能够用于任意用途。
- `agent`：智能体（Agent）场景使用的文件。

**scope_id** `string` | 作用域 ID（Session 维度）

当前仅支持传入 Session ID，用于筛选该 Session 在 `/mnt/session/outputs/` 目录中生成的产物。

> **说明：注意**
>
> * 仅适用于 [Managed Agents](/docs/overview) 场景。
>
> * 参数取值必须为合法有效的会话 ID。

## 响应参数

**data** `object[]` | 文件列表

文件对象列表，元素结构与 [查询文件详情](/docs/search-files-api) 接口返回的单个文件对象一致

**created_at** `integer` | 创建时间

`data.created_at`

文件上传时的 Unix 时间戳（秒）

**expire_at** `integer` | 过期时间

`data.expire_at`

文件过期时间的 Unix 时间戳（秒）。文件过期后将无法访问，需重新上传

**filename** `string` | 原始文件名

`data.filename`

上传时的原始文件名

**id** `string` | 文件 ID

`data.id`

文件的唯一标识符

**object** `string` | 对象类型

`data.object`

对象类型，固定为 `file`

**purpose** `string` | 文件用途

`data.purpose`

文件用途。

- `user_data`：可以灵活使用的文件，能够用于任意用途。
- `agent`：智能体（Agent）场景使用的文件。

**status** `string` | 文件状态

`data.status`

文件处理状态。常见取值为 `active`（处理完成，可用于推理）、`processing`（处理中）、`failed`（处理失败）

**bytes** `integer` | 文件大小

`data.bytes`

文件大小，单位为字节（Bytes）

> **说明：注意**
>
> 仅在文件处理状态 `status` 为 `active` 时返回。

**download_url** `string` | 下载 URL

`data.download_url`

服务端签发的临时预签名下载地址，可用于下载文件内容。

> **注意**
>
> 该地址包含临时访问凭证。请仅向已授权用户提供，并避免写入日志、长期缓存或公开分享。

**error** `object` | 错误信息

`data.error`

文件上传或处理失败时返回的错误信息对象，包含错误码、错误消息等字段

> **说明：注意**
>
> 仅在文件处理状态 `status` 为 `failed` 时返回。

**code** `string` | 错误码

`data.error.code`

机器可读的错误码

**message** `string` | 错误消息

`data.error.message`

人类可读的错误描述信息

**param** `string` | 错误参数

`data.error.param`

触发该错误的请求参数名（如有）

**type** `string` | 错误类型

`data.error.type`

错误类型标识

**mime_type** `string` | MIME 类型

`data.mime_type`

文件的 MIME 类型，例如 `video/mp4`、`image/jpeg`

**preprocess_configs** `object` | 预处理配置

`data.preprocess_configs`

上传文件时设置的预处理规则配置，按文件类型分组（如视频抽帧规则）

**video** `object` | 视频预处理配置

`data.preprocess_configs.video`

视频文件的预处理配置

**fps** `number` | 抽帧帧率

`data.preprocess_configs.video.fps`

视频抽帧的帧率（Frames Per Second），用于设置视频预处理时每秒采样的画面帧数

**model** `string` | 预处理模型

`data.preprocess_configs.video.model`

视频预处理使用的模型标识符（可选）

**scope** `object` | 文件所属作用域信息

`data.scope`

文件所属作用域信息，用于标识该文件创建时归属的会话上下文。

**id** `string` | 作用域 ID

`data.scope.id`

作用域 ID，返回对应的会话 ID。

**type** `string` | 作用域类型

`data.scope.type`

作用域类型，当前固定取值为 `session`。

**first_id** `string` | 首条文件 ID

当前响应中第一条文件数据的 ID

**has_more** `boolean` | 是否有更多数据

标识是否还有更多数据未返回：
* `true`：存在未返回的数据，可继续使用 `last_id` 作为 `after` 拉取下一页；
* `false`：已返回全部数据

**last_id** `string` | 末条文件 ID

当前响应中最后一条文件数据的 ID，可用作下一页请求的 `after` 参数

**object** `string` | 对象类型

对象类型，固定为 `list`


## 代码示例

## 默认

### cURL


#### Request

```bash
curl https://ark.cn-beijing.volces.com/api/v3/files \
-H "Authorization: Bearer $ARK_API_KEY"
```
#### Response

```
{
    "object": "file",
    "data": [
        {
            "object": "file",
            "id": "file-20251014203105-ll4pb",
            "purpose": "user_data",
            "filename": "demo.mp4",
            "bytes": 109322727,
            "mime_type": "video/mp4",
            "created_at": 1760445065,
            "expire_at": 1760704264,
            "status": "active"
        },
        {
            "object": "file",
            "id": "file-20251014203036-24jvn",
            "purpose": "user_data",
            "filename": "demo.png",
            "bytes": 601,
            "mime_type": "image/png",
            "created_at": 1760445036,
            "expire_at": 1760704236,
            "status": "active"
        }
    ],
    "first_id": "file-20251014203105-ll4pb",
    "last_id": "file-20251014203036-24jvn",
    "has_more": false
}
```

### Python


#### Request

```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)
```
#### Response

```
{
    "object": "file",
    "data": [
        {
            "object": "file",
            "id": "file-20251014203105-ll4pb",
            "purpose": "user_data",
            "filename": "demo.mp4",
            "bytes": 109322727,
            "mime_type": "video/mp4",
            "created_at": 1760445065,
            "expire_at": 1760704264,
            "status": "active"
        },
        {
            "object": "file",
            "id": "file-20251014203036-24jvn",
            "purpose": "user_data",
            "filename": "demo.png",
            "bytes": 601,
            "mime_type": "image/png",
            "created_at": 1760445036,
            "expire_at": 1760704236,
            "status": "active"
        }
    ],
    "first_id": "file-20251014203105-ll4pb",
    "last_id": "file-20251014203036-24jvn",
    "has_more": false
}
```

### 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.ListFiles(ctx, &file.FilesListParams{})
    if err != nil {
        fmt.Printf("get file List error: %v", err)
        return
    }
    fmt.Printf("file List: %v", fileInfo)
}
```

#### Response

```
{
    "object": "file",
    "data": [
        {
            "object": "file",
            "id": "file-20251014203105-ll4pb",
            "purpose": "user_data",
            "filename": "demo.mp4",
            "bytes": 109322727,
            "mime_type": "video/mp4",
            "created_at": 1760445065,
            "expire_at": 1760704264,
            "status": "active"
        },
        {
            "object": "file",
            "id": "file-20251014203036-24jvn",
            "purpose": "user_data",
            "filename": "demo.png",
            "bytes": 601,
            "mime_type": "image/png",
            "created_at": 1760445036,
            "expire_at": 1760704236,
            "status": "active"
        }
    ],
    "first_id": "file-20251014203105-ll4pb",
    "last_id": "file-20251014203036-24jvn",
    "has_more": false
}
```

### Java


#### Request

```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();
    }
}
```

#### Response

```
{
    "object": "file",
    "data": [
        {
            "object": "file",
            "id": "file-20251014203105-ll4pb",
            "purpose": "user_data",
            "filename": "demo.mp4",
            "bytes": 109322727,
            "mime_type": "video/mp4",
            "created_at": 1760445065,
            "expire_at": 1760704264,
            "status": "active"
        },
        {
            "object": "file",
            "id": "file-20251014203036-24jvn",
            "purpose": "user_data",
            "filename": "demo.png",
            "bytes": 601,
            "mime_type": "image/png",
            "created_at": 1760445036,
            "expire_at": 1760704236,
            "status": "active"
        }
    ],
    "first_id": "file-20251014203105-ll4pb",
    "last_id": "file-20251014203036-24jvn",
    "has_more": false
}
```

### Python-OpenAI


#### Request

```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)
```
#### Response

```
{
    "object": "file",
    "data": [
        {
            "object": "file",
            "id": "file-20251014203105-ll4pb",
            "purpose": "user_data",
            "filename": "demo.mp4",
            "bytes": 109322727,
            "mime_type": "video/mp4",
            "created_at": 1760445065,
            "expire_at": 1760704264,
            "status": "active"
        },
        {
            "object": "file",
            "id": "file-20251014203036-24jvn",
            "purpose": "user_data",
            "filename": "demo.png",
            "bytes": 601,
            "mime_type": "image/png",
            "created_at": 1760445036,
            "expire_at": 1760704236,
            "status": "active"
        }
    ],
    "first_id": "file-20251014203105-ll4pb",
    "last_id": "file-20251014203036-24jvn",
    "has_more": false
}
```