# 通过 TOS 内网预签名 URL 传入文件

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

您可以将文件存储在华北2（cn-beijing）Region 的私有对象存储桶（TOS）中，通过内网（火山引擎云内部网络）域名生成 GET 预签名 URL，在不公开源文件的前提下，将图片、视频等文件传入火山方舟。生成的预签名 URL 示例如下：

```text
https://your-private-bucket.tos-cn-beijing.ivolces.com/path/to/object?...signature...
```

该方式具有以下优势：

* 链接无法通过外网（公开可访问网络）直接访问源文件，数据安全性更高。
* 不消耗公网流量，可降低网络成本，并提升文件传输效率。

> **注意**
>
> TOS 存储桶、TOS 内网域名与火山方舟服务需保持在华北2（cn-beijing）Region。

## 步骤一：生成 TOS 内网预签名 URL

针对已存储在 TOS 中的对象，生成一个仅用于读取的 GET 预签名 URL。

配置以下环境变量：

```bash
# TOS 访问凭证（Access Key / Secret Key）
export TOS_ACCESS_KEY="YOUR_TOS_ACCESS_KEY"  # TOS Access Key/Secret Key 请从火山引擎控制台的访问密钥管理获取，ARK_API_KEY 请从火山方舟控制台的 API Key 页面获取
export TOS_SECRET_KEY="YOUR_TOS_SECRET_KEY"

# 火山方舟 API Key
export ARK_API_KEY="YOUR_ARK_API_KEY"
```

以视频文件为例，示例代码如下：

```Python
import os
import tos
from tos.enum import HttpMethodType

ak = os.getenv("TOS_ACCESS_KEY")
sk = os.getenv("TOS_SECRET_KEY")
endpoint = "tos-cn-beijing.ivolces.com"  # TOS 内网 Endpoint，仅支持 cn-beijing Region
region = "cn-beijing"                     # 当前仅支持 cn-beijing Region
bucket_name = "your-private-bucket"       # 替换为实际的 Bucket 名称
object_key = "path/to/object.mp4"        # 替换为实际的对象路径

if not ak or not sk:
    raise ValueError("Missing TOS_ACCESS_KEY or TOS_SECRET_KEY")
client = tos.TosClientV2(ak, sk, endpoint, region)
try:
    output = client.pre_signed_url(
        HttpMethodType.Http_Method_Get,
        bucket_name,
        object_key,
        expires=3600,  # 预签名 URL 有效期（秒），过期后 URL 失效，需重新生成
    )
    print(output.signed_url)
except tos.exceptions.TosClientError as e:
    print("Client error:", e.message, e.cause)
except tos.exceptions.TosServerError as e:
    print("Server error:", e.code, e.message, e.request_id)
except Exception as e:
    print("Unknown error:", e)
```

> **说明**
>
> 预签名 URL 存在有效期限制，可通过 `expires` 参数设置，详情参见 [普通预签名](https://docs.volcengine.com/docs/6349/129226?_vtm_=a106466.b106468.0_0.0_0.0.2289_7630866813484467762&lang=zh)。

示例输出：

```
https://your-private-bucket.tos-cn-beijing.ivolces.com/path/to/object?...signature...
```

> 该 URL 仅可被华北2（cn-beijing）Region 内的火山引擎基础设施访问（如火山方舟），无法通过外网直接访问。

## 步骤二：使用预签名 URL 调用火山方舟

将步骤一生成的预签名 URL 作为 `video_url` 传入模型，对视频内容进行理解。

示例代码如下：

```python
import os
from arkruntime import Ark

client = Ark(
    api_key=os.getenv("ARK_API_KEY"),
    base_url="https://ark.cn-beijing.volces.com/api/v3",
)
# 替换为步骤一生成的预签名 URL
video_url = "https://your-private-bucket.tos-cn-beijing.ivolces.com/path/to/object.mp4?...signature..."
resp = client.chat.completions.create(
    # Replace with Model ID
    model="doubao-seed-2-1-pro-260915",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "请理解这个视频，输出：1. 视频主要内容 2. 关键人物/物体 3. 关键动作 4. 场景变化 5. 一段简短摘要"
                },
                {
                    "type": "video_url",
                    "video_url": {
                        "url": video_url
                    }
                }
            ],
        }
    ],
)

print(resp.choices[0].message.content)
```

* 按需替换 Model ID，查询 Model ID 参见 [模型列表](/docs/model-list)。

## 常见问题

### 方舟无法读取输入文件

请优先检查以下内容：

1. TOS Bucket 与火山方舟服务是否位于华北2（cn-beijing）Region。
2. 是否使用了正确的内网域名，例如华北2（cn-beijing）Region 的 `tos-cn-beijing.ivolces.com`。
3. 预签名 URL 是否已过期。
4. 对象是否存在，且对象 Key 与签名时使用的值完全一致。
5. URL 是否在传递过程中被截断、重复编码或丢失查询参数。
6. 所选模型是否支持当前输入类型。