文件与媒体输入、输出及生命周期

小白：四种输入方式

URL 适合已在对象存储中的文件；Base64 或 data URL 适合小型一次性输入；multipart 适合音频转写和图像编辑等文件表单；厂商原生 Files API 适合上游明确支持的复用上传。本站 /v1/files 当前返回未实现，因此不能先上传再假定所有模型都能引用文件 ID。

调用下面的转写示例前先准备本站地址和 API Key：

Copyexport BASE_URL="https://api.tu-zi.com"
export API_KEY="你的本站 API Key"

Copycurl "$BASE_URL/v1/audio/transcriptions"   -H "Authorization: Bearer $API_KEY"   -F "model=gpt-4o-mini-transcribe"   -F "file=@sample.mp3"

请求前在模型广场核对音频端点，并以实际协议要求的字段、MIME 和格式为准。

支持矩阵应由端点决定

聊天视觉可能接受远程 URL 或 data URL，图像编辑通常需要 multipart 或参考图字段，音频转写使用 multipart，视频生成可能接受图片 URL 或厂商资产 ID。不要把一种端点成功的 file_id、URL 或字段复制到另一种协议。Base64 会增加体积，也会扩大日志和内存风险。

URL 输入的安全边界

服务端抓取 URL 前应只允许 HTTPS，解析 DNS 后阻止环回、私网、链路本地和云元数据地址，并在每次重定向后重新校验。限制重定向次数、连接/读取超时、响应大小和 Content-Type；MIME 头不能代替魔数检查。不要把带凭证的内网 URL 直接交给第三方模型厂商。

上传与内存

网关和客户端应流式读取 multipart，设置总请求体与单文件上限，并尽早拒绝不支持的格式。不要一次载入大视频；临时文件要使用不可猜名称、最小权限和确定清理。日志只记录大小、摘要、MIME 和对象 ID，不记录完整 Base64 或签名 URL。

结果与生命周期

同步结果可能是 Base64 或短期 URL；异步任务还可能返回二进制结果信封。先验证状态、类型、长度与摘要，再流式写入自有对象存储。保存业务副本后再认为交付完成；对 expired 或 410 不应无限重试原下载地址。

专家治理

建立输入数据分级、允许格式、病毒扫描、图像解码炸弹防护、租户目录隔离和删除传播。记录上游厂商、区域、保留政策、任务 ID 和结果删除时间。容量规划同时考虑网络带宽、临时磁盘、对象存储、并发连接与 Base64 膨胀，而不仅是请求数量。

MiniMax M3：上传视频后通过 URL 理解视频

POST /v1/media/video 是本站扩展接口，复用 H3 临时对象存储。使用本站 API Key，以 multipart/form-data 恰好提交 model 和 file 两个字段；模型仅支持 MiniMax-M3.1-Flash、MiniMax-M3，令牌必须有该模型及可用渠道的权限。接受 MP4、MOV、AVI、MKV，按文件签名检查，单文件最多 50,000,000 字节；容器内编码是否受支持仍以上游实际处理为准。

成功响应包含 url、bytes、mime_type、delete_token。将 url 放入聊天请求的 messages[].content[].video_url.url。这是视频理解输入，不是 H3 视频生成任务；不会生成 MiniMax file_id 或 mm_file://，也不支持 Files API 的大文件额度。已有公网视频 URL 可以直接传入聊天接口。

上传要求管理员启用可被上游公网访问、支持删除的 staging 存储，并配置稳定的加密密钥。URL 是持有即可访问的共享链接，请勿当作按用户鉴权的私有下载。文件保留时间取决于存储生命周期配置，接口不保证固定有效期；请安全保存删除凭证，在推理全部结束后主动删除。删除要求同一用户、同一应用身份及有效本站令牌，不需要再次具备模型调用权限；删除失败可使用同一凭证重试。存储配置或加密密钥变更可能影响旧凭证，请先清理旧文件。对象删除不等于清除 CDN 缓存或已被下载的副本。

上传及删除接口共用每用户每分钟 10 次限流，单进程最多 4 个并发上传，连续 30 秒没有读取到请求数据会超时。视频推理沿用模型 usage 计费，上传接口本身不扣模型 token 额度。

Copyexport BASE_URL="https://api.tu-zi.com"
export API_KEY="YOUR_SITE_API_KEY"
# Requires curl and jq. Keep upload.json private: it contains the deletion receipt.
umask 077
curl --fail-with-body "$BASE_URL/v1/media/video" \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=MiniMax-M3.1-Flash" -F "file=@sample.mp4" > upload.json

jq -n --arg url "$(jq -r .url upload.json)" \
  '{model:"MiniMax-M3.1-Flash",max_tokens:512,messages:[{role:"user",content:[{type:"text",text:"Describe this video."},{type:"video_url",video_url:{url:$url}}]}]}' \
  > chat.json
curl --fail-with-body "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  --data-binary @chat.json

# Delete only after all requests using the URL have finished.
jq '{delete_token}' upload.json > delete.json
curl --fail-with-body "$BASE_URL/v1/media/video/delete" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  --data-binary @delete.json