您可以将文件存储在华北2(cn-beijing)Region 的私有对象存储桶(TOS)中,通过内网(火山引擎云内部网络)域名生成 GET 预签名 URL,在不公开源文件的前提下,将图片、视频等文件传入火山方舟。生成的预签名 URL 示例如下:
https://your-private-bucket.tos-cn-beijing.ivolces.com/path/to/object?...signature...
该方式具有以下优势:
- 链接无法通过外网(公开可访问网络)直接访问源文件,数据安全性更高。
- 不消耗公网流量,可降低网络成本,并提升文件传输效率。
步骤一:生成 TOS 内网预签名 URL#
针对已存储在 TOS 中的对象,生成一个仅用于读取的 GET 预签名 URL。
配置以下环境变量:
# 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"
以视频文件为例,示例代码如下:
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 传入模型,对视频内容进行理解。
示例代码如下:
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 参见 模型列表。
常见问题#
方舟无法读取输入文件#
请优先检查以下内容:
- TOS Bucket 与火山方舟服务是否位于华北2(cn-beijing)Region。
- 是否使用了正确的内网域名,例如华北2(cn-beijing)Region 的
tos-cn-beijing.ivolces.com。 - 预签名 URL 是否已过期。
- 对象是否存在,且对象 Key 与签名时使用的值完全一致。
- URL 是否在传递过程中被截断、重复编码或丢失查询参数。
- 所选模型是否支持当前输入类型。