# 查询文件详情

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

`GET https://ark.cn-beijing.volces.com/api/v3/files/{file_id}`

通过文件 ID 查询指定文件的详细信息。

## 鉴权

本接口支持鉴权方式如下，详情请参见 [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>
## 请求参数

### Path 参数

**file_id** `string` `必选` | 文件 ID

要查询的文件 ID

## 响应参数

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

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

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

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

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

上传时的原始文件名

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

文件的唯一标识符

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

对象类型，固定为 `file`

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

文件用途。

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

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

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

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

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

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

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

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

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

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

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

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

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

`error.code`

**message** `string` | 错误描述信息

`error.message`

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

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

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

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

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

`preprocess_configs.video`

视频文件的预处理配置

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

`preprocess_configs.video.fps`

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

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

`preprocess_configs.video.model`

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

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

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

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

`scope.id`

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

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

`scope.type`

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


## 代码示例

## 默认

### cURL


#### Request

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

```
{
    "object": "file",
    "id": "file-20251119****",
    "purpose": "user_data",
    "filename": "demo.mp4",
    "bytes": 18773126,
    "mime_type": "video/mp4",
    "created_at": 1763552708,
    "expire_at": 1764157507,
    "status": "active"
}
```

### Python


#### Request

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

#### Response

```
{
    "object": "file",
    "id": "file-20251119****",
    "purpose": "user_data",
    "filename": "demo.mp4",
    "bytes": 18773126,
    "mime_type": "video/mp4",
    "created_at": 1763552708,
    "expire_at": 1764157507,
    "status": "active"
}
```

### Go


#### Request

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

}
```

#### Response

```
{
    "object": "file",
    "id": "file-20251119****",
    "purpose": "user_data",
    "filename": "demo.mp4",
    "bytes": 18773126,
    "mime_type": "video/mp4",
    "created_at": 1763552708,
    "expire_at": 1764157507,
    "status": "active"
}
```

### 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();

        // Retrieve the file metadata.
        FileObject fileMeta = service.retrieveFile("file-20251119****");
        System.out.println("Retrieve File:" + fileMeta);

        service.shutdownExecutor();
    }
}
```

#### Response

```
{
    "object": "file",
    "id": "file-20251119****",
    "purpose": "user_data",
    "filename": "demo.mp4",
    "bytes": 18773126,
    "mime_type": "video/mp4",
    "created_at": 1763552708,
    "expire_at": 1764157507,
    "status": "active"
}
```

### 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,
)

# Retrieve the file metadata.
response = client.files.retrieve(
    file_id="file-20251119****"
)

print(response)
```

#### Response

```
{
    "object": "file",
    "id": "file-20251119****",
    "purpose": "user_data",
    "filename": "demo.mp4",
    "bytes": 18773126,
    "mime_type": "video/mp4",
    "created_at": 1763552708,
    "expire_at": 1764157507,
    "status": "active"
}
```