面向 AI 助手:本页的 Markdown 版本位于 https://ark.volcengine.com/region:cn-beijing/docs/upload-files-via-tos-internal-presigned-url.md,全部文档索引见 https://ark.volcengine.com/llms.txt。

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

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

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

该方式具有以下优势:

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

步骤一:生成 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)

示例输出:

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 参见 模型列表。

常见问题#

方舟无法读取输入文件#

请优先检查以下内容:

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