媒体、Files、Batches 与异步 API

本页覆盖普通 Chat、Responses、Messages 和 Embeddings 之外的接口。先确认当前构建是否提供可创建的 Provider Profile，再按 Project 授权和 Route 配置调用。端点标为 experimental 只表示契约成熟度， 不表示当前构建一定存在可用目标。

调用前检查

1. 在 Providers 中确认所需 Profile 没有标为 withheld，且 Provider 连接测试通过。
2. 在 Deployments 中确认真实模型、能力、价格版本和并发上限。
3. 在 Routes 中为操作创建公开别名。资源类 Route 必须唯一解析到一个 eligible Deployment。
4. 在 Projects 中授权该别名并配置预算、限流和策略。
5. 使用 Project Gateway Key 调用；创建资源时保存 Halro 返回的 opaque ID。

当前构建不提供 Bedrock Runtime/Agent Runtime Profile，因此 /v1/rerank 和 /v1/async/invocations 暂无可创建的后端。接口契约仍保留用于兼容性开发，不能作为已经可用的声明。

内容安全与媒体

Moderations、Images、Speech 和 Transcriptions 都使用普通 Gateway Key，并通过请求中的 model 解析 Route。下面先给出最小请求，随后列出当前源码接受的字段和约束。实验页只列契约中的字段名、 状态语义和偏差，不是带类型与必填关系的完整 Schema。

curl https://halro.example.com/v1/moderations \
  -H "Authorization: Bearer $HALRO_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"moderation","input":"待检查内容"}'

curl https://halro.example.com/v1/images/generations \
  -H "Authorization: Bearer $HALRO_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"image","prompt":"一只纸艺风格的猫","n":1,"size":"1024x1024"}'

curl https://halro.example.com/v1/audio/speech \
  -H "Authorization: Bearer $HALRO_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"speech","input":"你好","voice":"alloy"}' \
  --output speech.bin

curl https://halro.example.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $HALRO_GATEWAY_KEY" \
  -F model=transcription -F file=@sample.wav

媒体质量、安全性和真实 Provider 可用性必须另做验收。协议 fixture 只能证明请求和响应形状。

当前接受的媒体字段

JSON 端点使用严格解码，未知字段会被拒绝。表中“可选”只表示网关接受，仍需满足目标 Profile 的 能力约束。

当前接受的媒体字段

端点	必填	可选与范围
Moderations	input（有效且非 null 的 JSON）	model；省略时为 omni-moderation-latest
Images	prompt（非空字符串）	model、quality、response_format、size、style；n 默认 1，范围 1–10
Speech	model、非空 input、voice	response_format；speed 范围 0.25–4
Transcriptions	multipart 中恰好一个 file 和非空 model	language、prompt、response_format；temperature 范围 0–1

Transcriptions 的未知 multipart 字段、重复 File 或没有文件名的 File 都会返回 400。

Files 与 Batches

File 的 multipart body 没有 model，因此必须通过 Halro-Route 指定资源 Route。创建型请求应使用 稳定的 Idempotency-Key；只有在业务操作相同时才复用同一个值。

FILE_RESPONSE=$(curl -fsS https://halro.example.com/v1/files \
  -H "Authorization: Bearer $HALRO_GATEWAY_KEY" \
  -H "Halro-Route: batch-files" \
  -H "Idempotency-Key: order-20260905-file-v1" \
  -F purpose=batch -F file=@input.jsonl)

从响应保存 id，再用它创建 Batch。Batch 继承 input File 已绑定的 Provider、Deployment、Profile 和 Region，不重新选 Route。

curl https://halro.example.com/v1/batches \
  -H "Authorization: Bearer $HALRO_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20260905-batch-v1" \
  -d '{"input_file_id":"file_...","endpoint":"/v1/chat/completions","completion_window":"24h"}'

用 GET /v1/batches/{id} 有界轮询。进入终态后保存 output_file_id 或 error_file_id，再通过 GET /v1/files/{id}/content 读取。依赖资源尚未保存前不要删除输入 File；删除会同时移除上游对象、 Halro metadata 与本地内容。

Files 与 Batches 字段

Files 与 Batches 字段

操作	请求头或必填字段	可选与范围
创建 File	Authorization、Halro-Route、稳定的 Idempotency-Key；multipart file、purpose	不接受其他 multipart 字段；只允许一个带文件名的 File
创建 Batch	input_file_id、endpoint、completion_window="24h"；稳定的 Idempotency-Key	metadata 最多 16 项；Key 长度 1–64，Value 最长 512
查询、取消 Batch	路径中的 opaque Batch ID	无请求正文；返回创建时绑定目标的状态
查询、下载、删除 File	路径中的 opaque File ID	无请求正文；仅创建它的 Project 可见

Batch 的 endpoint 还受 input File 创建时绑定的 Profile 限制：

Files 与 Batches 字段

绑定 Profile	endpoint 可接受值	completion_window
openai.media-resources.v1	/v1/chat/completions、/v1/responses、/v1/embeddings	只能是 24h
anthropic.messages.2023-06-01	只能是 /v1/chat/completions	只能是 24h

Rerank 与异步生成

这两个接口当前保留契约，但本构建没有可创建的 Provider Profile：

• POST /v1/rerank 需要 Bedrock Agent Runtime Rerank Profile；
• POST /v1/async/invocations 需要 Bedrock Runtime Async Profile。

在未来构建解除 withheld 前，不要把它们写入生产集成或验收清单。解除后，创建请求仍需要稳定 Idempotency-Key；Async 的查询返回项目归属记录，取消当前 fail closed，不能把 409 解释成任务已停止。

Rerank 与异步生成

端点	必填	可选与范围
Rerank	model:string、非空 query:string（最多 10,000 字节）、documents:string[]（1–1,000 项；每项非空且最多 50,000 字节）	top_n:int 默认文档数，范围 1–文档数
Async 创建	model:string、非空 prompt:string（最多 512 字节）、s3_output_uri:string	duration_seconds:int、dimension:string、fps:string、seed:int64；当前网关不额外声明枚举或数值范围
Async 查询、取消	路径中的 opaque Invocation ID	无请求正文；取消未得到上游确认时失败关闭

以上 JSON 请求都拒绝未知字段。即使字段格式正确，当前构建仍会因没有可创建 Profile 而无法配置 Rerank 与 Async 的后端。

Async 的 s3_output_uri 必须使用 s3://，包含非空 bucket，路径以 / 结尾，并且不能包含用户信息、 query 或 fragment。该 URI 会交给已绑定的 Bedrock 目标，不接受 HTTP URL。

资源边界与重试

• File 最长保留 30 天；Batch 和 Async 记录最长保留 7 天。
• 资源 ID 只对创建它的 Project 可见，不能跨 Project 查询或删除。
• 读取、取消和删除回到创建时绑定的目标，不进行 fallback。
• 429 按 Retry-After 有界退避。若已保存资源 ID，先查询该资源；若创建响应没有返回 ID，则以相同 Idempotency-Key、相同正文和相同归因做有界退避重试。持续返回 409 时保留原 Key、停止新建并交给管理员处理。
• 删除资源不会撤销已经发生的 Provider 费用。

完整重试规则见重试、超时与幂等，成熟度、字段名和契约偏差见 实验性端点一览。