实验性端点一览
| 端点 | 语义操作 | 本构建 | 请求字段 | 响应字段 | 状态语义 |
|---|---|---|---|---|---|
POST /halro/v1/runs | governance | 可配置；仍为 experimental | 3 | 5 | ledger-authoritative idempotent Run creation |
GET /halro/v1/runs/{id} | governance | 可配置；仍为 experimental | 1 | 7 | project-owned ledger-derived Run read |
POST /halro/v1/runs/{id}/close | governance | 可配置；仍为 experimental | 2 | 4 | ledger-authoritative idempotent Run close |
POST /halro/v1/work-units | governance | 可配置；仍为 experimental | 1 | 4 | ledger-authoritative idempotent Work Unit creation |
GET /halro/v1/work-units/{id} | governance | 可配置；仍为 experimental | 1 | 3 | project-owned dual-source read: Work Unit and Runs from Accounting Ledger, Outcomes from Governance Journal |
POST /halro/v1/work-units/{id}/close | governance | 可配置；仍为 experimental | 1 | 4 | ledger-authoritative idempotent Work Unit close |
POST /halro/v1/work-units/{id}/outcomes | governance | 可配置；仍为 experimental | 7 | 11 | governance-journal-authoritative idempotent Outcome report |
POST /v1/async/invocations | async_generate | 不可服务（无可创建 Profile） | 7 | 6 | project-owned resource with 7 day TTL |
GET /v1/async/invocations/{id} | async_generate | 不可服务（无可创建 Profile） | 1 | 6 | project-owned resource |
POST /v1/async/invocations/{id}/cancel | async_generate | 不可服务（无可创建 Profile） | 1 | 1 | always fails closed because Bedrock has no cancellation operation |
POST /v1/audio/speech | synthesize | 可配置；仍为 experimental | 5 | 1 | stateless |
POST /v1/audio/transcriptions | transcribe | 可配置；仍为 experimental | 6 | 1 | stateless |
POST /v1/batches | batch | 可配置；仍为 experimental | 4 | 16 | project-owned resource with 7 day TTL |
GET /v1/batches/{id} | batch | 可配置；仍为 experimental | 1 | 16 | project-owned resource |
POST /v1/batches/{id}/cancel | batch | 可配置；仍为 experimental | 1 | 16 | project-owned cancellable resource |
POST /v1/files | file | 可配置；仍为 experimental | 3 | 8 | project-owned resource with 30 day TTL |
GET /v1/files/{id} | file | 可配置；仍为 experimental | 1 | 8 | project-owned resource |
DELETE /v1/files/{id} | file | 可配置；仍为 experimental | 1 | 3 | deletes upstream, metadata, and local content |
GET /v1/files/{id}/content | file | 可配置；仍为 experimental | 1 | 1 | content served from the private local object directory |
POST /v1/images/generations | image | 可配置；仍为 experimental | 7 | 5 | stateless |
GET /v1/models | discovery | 本地查询；仍为 experimental | 0 | 6 | read of the caller’s Project configuration and the live route table; no provider I/O |
GET /v1/models/{id} | discovery | 本地查询；仍为 experimental | 1 | 4 | read of the caller’s Project configuration and the live route table; no provider I/O |
POST /v1/moderations | moderate | 可配置；仍为 experimental | 2 | 3 | stateless |
POST /v1/rerank | rerank | 不可服务（无可创建 Profile） | 4 | 1 | stateless Halro extension |
GET /v1/responses/{id} | generate | 可配置；仍为 experimental | 1 | 10 | project-owned deferred record; polling is authoritative and writes no accounting events |
DELETE /v1/responses/{id} | generate | 可配置；仍为 experimental | 1 | 3 | project-owned deferred record |
POST /v1/responses/{id}/cancel | generate | 可配置；仍为 experimental | 1 | 10 | project-owned deferred record |
公共契约偏差
Section titled “公共契约偏差”以下限制被多个端点共同声明，只列一次：
- 操作结论：只发送字段表及所选 Profile 支持的字段；未知或该 Profile 不支持的字段会在 Provider I/O 前被拒绝。 原始契约：unknown fields and unsupported profile fields are rejected before provider I/O
- 操作结论：资源 ID 是 Halro 生成的不透明值，只在创建它的 Project 内有效；查询、删除和取消都必须使用同一 Project 的 Key。 原始契约：resource identifiers are opaque Halro identifiers scoped to one project
- 操作结论：此资源面每次调用都要求
inferenceScope；缺少时在查询或 Provider I/O 前返回403 gateway_key_scope_denied。 原始契约：every call on this plane requires the Gateway Key’s inference scope and is refused with 403 gateway_key_scope_denied before lookup or Provider I/O when that grant is absent - 操作结论：不存在的资源在记账前返回 404；所有已认证资源面请求（包括权限拒绝）仍计入固定 Key/Project 上限，即使 Project RPM 不限也可能返回 429。 原始契约：an identifier that names nothing answers 404 before any accounting is opened, so it consumes no Project rate limit or budget; every authenticated call on this plane, including scope and source-policy refusals, is instead charged against a fixed per-minute ceiling on the calling Key and on its Project, and a 429 rate_limit_exceeded is therefore possible where the Project’s own RPM is unlimited
- 操作结论：Anthropic Batch 的输入文件只保存在 Halro，本身不会上传给 Provider；后续只能使用 Halro 返回的 File ID，不能把它当作上游文件 ID。 原始契约：a batch served by the Anthropic profile has its requests carried inline: the input file is stored by Halro and never uploaded, so its identifier names a Halro object rather than one the upstream also holds
- 操作结论：Provider 不返回结果文件时，Halro 只在响应上限内生成结果；超限 Batch 会标记不可交付，不会截断，调用方必须把它当作失败。 原始契约：results collected from a provider that does not return them as a file are bounded by the gateway’s response ceiling; a batch whose results exceed it is reported as undeliverable rather than truncated
- 操作结论：Anthropic Batch 只接受
completion_window=24h；其他 Provider 按其自身窗口契约处理。 原始契约：completion_window is honored only where the provider has one; the Anthropic profile expires a batch 24 hours after creation and accepts no other value - 操作结论：这是 Halro 扩展端点，没有 OpenAI 官方 SDK 方法；请直接按 Halro HTTP 契约调用。 原始契约：this is a Halro extension and has no OpenAI official SDK surface
- 操作结论：Run Governance 仍为 experimental；完成真实业务试点并验证 Work Unit 与 Outcome Definition 边界前，不得标记为生产成熟。 原始契约：Run Governance remains experimental until a real business pilot validates the Work Unit and Outcome Definition boundary
每个端点的字段与特有偏差
Section titled “每个端点的字段与特有偏差”展开一个端点即可看到它接受的请求头、请求字段、响应字段和只属于该端点的偏差。
POST /halro/v1/runs
- 请求头：
Authorization、Content-Type、Idempotency-Key - 路径参数：无
- 正文或表单字段：
work_unit_id、budget_micros_usd、ttl_seconds - 响应字段：
id、work_unit_id、budget_micros_usd、status、expires_at
GET /halro/v1/runs/{id}
- 请求头：
Authorization - 路径参数：
id - 正文或表单字段：无请求正文
- 响应字段：
id、work_unit_id、budget_micros_usd、committed_micros_usd、reserved_micros_usd、unknown_attempts、status
POST /halro/v1/runs/{id}/close
- 请求头：
Authorization、Content-Type、Idempotency-Key - 路径参数：
id - 正文或表单字段：
reason - 响应字段：
id、status、closed_at、close_reason
POST /halro/v1/work-units
- 请求头：
Authorization、Content-Type、Idempotency-Key - 路径参数：无
- 正文或表单字段：
outcome_definition_ids - 响应字段：
id、project_id、status、created_at
GET /halro/v1/work-units/{id}
- 请求头：
Authorization - 路径参数：
id - 正文或表单字段：无请求正文
- 响应字段：
work_unit、runs、outcomes
POST /halro/v1/work-units/{id}/close
- 请求头：
Authorization、Content-Type、Idempotency-Key - 路径参数：
id - 正文或表单字段：必需空 JSON 对象
{} - 响应字段：
id、project_id、status、closed_at
POST /halro/v1/work-units/{id}/outcomes
- 请求头：
Authorization、Content-Type、Idempotency-Key - 路径参数：
id - 正文或表单字段：
definition_id、value、observed_at、evidence_ref、evidence_sha256、supersedes_outcome_id - 响应字段：
id、work_unit_id、definition_id、definition_version、value、reporter_key_id、observed_at、ingested_at、revision、governance_sequence、provisional
POST /v1/async/invocations
- 请求头：
Authorization、Content-Type、Idempotency-Key - 路径参数：无
- 正文或表单字段：
model、prompt、s3_output_uri、duration_seconds、dimension、fps、seed - 响应字段：
invocation_arn、status、s3_output_uri、failure_message、submitted_at、last_modified_at - 本构建不可服务：唯一对应的 Provider Profile 被 withheld，无法新建 Deployment。
GET /v1/async/invocations/{id}
- 请求头：
Authorization - 路径参数：
id - 正文或表单字段：无请求正文
- 响应字段：
invocation_arn、status、s3_output_uri、failure_message、submitted_at、last_modified_at - 本构建不可服务：唯一对应的 Provider Profile 被 withheld，无法新建 Deployment。
POST /v1/async/invocations/{id}/cancel
- 请求头：
Authorization - 路径参数：
id - 正文或表单字段：无请求正文
- 响应字段：
error - 本构建不可服务：唯一对应的 Provider Profile 被 withheld，无法新建 Deployment。
POST /v1/audio/speech
- 请求头：
Authorization、Content-Type - 路径参数：无
- 正文或表单字段：
model、input、voice、response_format、speed - 响应字段：
binary audio
POST /v1/audio/transcriptions
- 请求头：
Authorization、Content-Type - 路径参数：无
- 正文或表单字段：
file、model、language、prompt、response_format、temperature - 响应字段：
text
POST /v1/batches
- 请求头：
Authorization、Content-Type、Idempotency-Key - 路径参数：无
- 正文或表单字段：
input_file_id、endpoint、completion_window、metadata - 响应字段：
id、object、endpoint、input_file_id、completion_window、status、output_file_id、error_file_id、created_at、expires_at、completed_at、failed_at、cancelling_at、cancelled_at、metadata、errors - 特有偏差：创建 Batch 前会按同一个已选 Profile 校验每一行；任一行含该 Profile 无法表达的字段都会让整批失败，先逐行预检。 原始契约：every line of the input is checked against the selected profile before the batch is created, because a batch is routed once for many requests; a line the profile cannot carry fails the batch and names itself
GET /v1/batches/{id}
- 请求头：
Authorization - 路径参数：
id - 正文或表单字段：无请求正文
- 响应字段：
id、object、endpoint、input_file_id、completion_window、status、output_file_id、error_file_id、created_at、expires_at、completed_at、failed_at、cancelling_at、cancelled_at、metadata、errors
POST /v1/batches/{id}/cancel
- 请求头：
Authorization - 路径参数：
id - 正文或表单字段：无请求正文
- 响应字段：
id、object、endpoint、input_file_id、completion_window、status、output_file_id、error_file_id、created_at、expires_at、completed_at、failed_at、cancelling_at、cancelled_at、metadata、errors
POST /v1/files
- 请求头：
Authorization、Content-Type、Idempotency-Key、Halro-Route - 路径参数：无
- 正文或表单字段：
file、purpose - 响应字段：
id、object、bytes、created_at、filename、purpose、status、status_details
GET /v1/files/{id}
- 请求头：
Authorization - 路径参数：
id - 正文或表单字段：无请求正文
- 响应字段：
id、object、bytes、created_at、filename、purpose、status、status_details
DELETE /v1/files/{id}
- 请求头：
Authorization - 路径参数：
id - 正文或表单字段：无请求正文
- 响应字段：
id、object、deleted
GET /v1/files/{id}/content
- 请求头：
Authorization - 路径参数：
id - 正文或表单字段：无请求正文
- 响应字段：
binary content
POST /v1/images/generations
- 请求头：
Authorization、Content-Type - 路径参数：无
- 正文或表单字段：
model、prompt、n、quality、response_format、size、style - 响应字段：
created、data、data[].url、data[].b64_json、data[].revised_prompt - 特有偏差：该 experimental 端点不接受 OpenAI
user字段；提交前必须删除它。 原始契约：the OpenAI user field is not accepted by this experimental tier
GET /v1/models
- 请求头：
Authorization - 路径参数：无
- 正文或表单字段：无请求正文
- 响应字段：
object、data、data[].id、data[].object、data[].created、data[].owned_by - 特有偏差：只返回 Project 授权别名与当前路由表实际提供别名的交集；授权但无可用路由表条目的别名不列出。 原始契约：the answer is the caller’s Project’s allowed aliases intersected with the aliases the route table serves; an alias the Project may name but no enabled route carries is omitted rather than listed as callable
- 特有偏差：模型发现没有查询参数契约；额外查询参数会被忽略，不用于分页或过滤。 原始契约：query parameters are ignored rather than refused: this endpoint models none, and OpenAI’s own takes none
- 特有偏差：模型发现需同时有
inference与discovery；缺少后者返回 403，但不影响原本已授权的模型调用。 原始契约：the key must carry the discovery scope as well as inference, and a key without it answers 403 gateway_key_scope_denied while still being able to call the aliases it was given: enumeration is granted per key rather than implied by the ability to call - 特有偏差：
id是实例中的公开别名，不是上游模型 ID；管理员可改变其 Deployment，列表只展示 Project 获授的别名。 原始契约：every id is a public model alias, not a model identifier: the upstream provider and model behind it are never disclosed, an operator may repoint it at another deployment at any time without the id changing, and the alias namespace is the instance’s rather than the Project’s — a Project is granted aliases from it, and is listed only the ones it was granted - 特有偏差：列表不保证 operation 兼容；仅支持另一操作的别名仍会列出，实际调用可能返回
400 unsupported_feature。 原始契约：listing means the alias will not answer 404 model_not_found; it does not mean the next call succeeds, and two cases are permanent rather than transient: an alias whose deployments support a different operation is listed here and answers 400 unsupported_feature on use, because one flat list cannot be per-operation — the caller’s operation is not known until they call - 特有偏差：所有 Deployment 不健康或暂停的别名仍可能列出，实际调用返回 503；不要把列表当健康检查。 原始契约：an alias whose every deployment is unhealthy or suspended is also listed, and the call answers 503: that state is a moment rather than a configuration, and omitting it would restore the empty model list with no explanation this endpoint exists to end
- 特有偏差：路由表因代理不可达或 capability drift 剔除的别名不会列出；此时它在调用端点也返回 404。 原始契约：an alias disappears from the answer while the route table itself excludes it — a reload that drops a provider whose egress proxy is unreachable, or a deployment withheld for capability drift — because in that state the alias answers 404 on every endpoint
- 特有偏差：
created固定为0，Halro 不伪造公开别名的创建时间。 原始契约：created is always 0: an alias is a name on a route, not a versioned object, and Halro does not invent a timestamp for it - 特有偏差：
owned_by固定为halro，不披露上游身份。 原始契约：owned_by is always halro: the object’s owner is the gateway, which is the truest statement the OpenAI model shape can carry about an alias - 特有偏差：列表按公开别名排序并去重，不保证其他顺序。 原始契约：the answer is ordered by alias and carries no duplicates; no other order is promised
- 特有偏差：公开别名可以包含斜杠或需 percent-encoding 的字符；查询支持转义和未转义路径写法。 原始契约：an alias containing a slash or a character needing percent-encoding is served at both spellings, escaped and unescaped, because a public alias is operator-supplied free text
- 特有偏差：查询不调用上游、不写 Ledger，也不消耗计费 Project 预算；固定 Key/Project 分钟上限不可关闭，超限返回 429 与
Retry-After。 原始契约：no upstream call is made, no ledger event is written, and no per-Project rate limit or budget is consumed; the bound is a fixed per-minute ceiling on the calling Key and on its Project that no configuration can disable, refused as 429 rate_limit_exceeded with Retry-After - 特有偏差：持久化配置未安全激活时，发现与推理一样返回
503 configuration_stale；不要绕过实例门禁。 原始契约：a durable configuration change that has not yet reached the running snapshots refuses this endpoint with 503 configuration_stale exactly as it refuses an inference call: the gate is the listener’s, ahead of the handler, and discovery is not exempt from it
GET /v1/models/{id}
- 请求头：
Authorization - 路径参数：
id - 正文或表单字段：无请求正文
- 响应字段：
id、object、created、owned_by - 特有偏差：单个别名不存在或 Project 无权访问都返回 404，不能据此枚举其他 Project 的别名。 原始契约：retrieving an alias the Project may not name answers 404 rather than 403, and so does one that does not exist anywhere, so the endpoint cannot be used to test whether an alias exists on another Project
- 特有偏差：模型发现需同时有
inference与discovery；缺少后者返回 403，但不影响原本已授权的模型调用。 原始契约：the key must carry the discovery scope as well as inference, and a key without it answers 403 gateway_key_scope_denied while still being able to call the aliases it was given: enumeration is granted per key rather than implied by the ability to call - 特有偏差：
id是实例中的公开别名，不是上游模型 ID；管理员可改变其 Deployment，列表只展示 Project 获授的别名。 原始契约：every id is a public model alias, not a model identifier: the upstream provider and model behind it are never disclosed, an operator may repoint it at another deployment at any time without the id changing, and the alias namespace is the instance’s rather than the Project’s — a Project is granted aliases from it, and is listed only the ones it was granted - 特有偏差：列表不保证 operation 兼容；仅支持另一操作的别名仍会列出，实际调用可能返回
400 unsupported_feature。 原始契约：listing means the alias will not answer 404 model_not_found; it does not mean the next call succeeds, and two cases are permanent rather than transient: an alias whose deployments support a different operation is listed here and answers 400 unsupported_feature on use, because one flat list cannot be per-operation — the caller’s operation is not known until they call - 特有偏差：所有 Deployment 不健康或暂停的别名仍可能列出，实际调用返回 503；不要把列表当健康检查。 原始契约：an alias whose every deployment is unhealthy or suspended is also listed, and the call answers 503: that state is a moment rather than a configuration, and omitting it would restore the empty model list with no explanation this endpoint exists to end
- 特有偏差：路由表因代理不可达或 capability drift 剔除的别名不会列出；此时它在调用端点也返回 404。 原始契约：an alias disappears from the answer while the route table itself excludes it — a reload that drops a provider whose egress proxy is unreachable, or a deployment withheld for capability drift — because in that state the alias answers 404 on every endpoint
- 特有偏差：
created固定为0，Halro 不伪造公开别名的创建时间。 原始契约：created is always 0: an alias is a name on a route, not a versioned object, and Halro does not invent a timestamp for it - 特有偏差：
owned_by固定为halro，不披露上游身份。 原始契约：owned_by is always halro: the object’s owner is the gateway, which is the truest statement the OpenAI model shape can carry about an alias - 特有偏差：列表按公开别名排序并去重，不保证其他顺序。 原始契约：the answer is ordered by alias and carries no duplicates; no other order is promised
- 特有偏差：公开别名可以包含斜杠或需 percent-encoding 的字符；查询支持转义和未转义路径写法。 原始契约：an alias containing a slash or a character needing percent-encoding is served at both spellings, escaped and unescaped, because a public alias is operator-supplied free text
- 特有偏差：查询不调用上游、不写 Ledger，也不消耗计费 Project 预算；固定 Key/Project 分钟上限不可关闭，超限返回 429 与
Retry-After。 原始契约：no upstream call is made, no ledger event is written, and no per-Project rate limit or budget is consumed; the bound is a fixed per-minute ceiling on the calling Key and on its Project that no configuration can disable, refused as 429 rate_limit_exceeded with Retry-After - 特有偏差：持久化配置未安全激活时，发现与推理一样返回
503 configuration_stale；不要绕过实例门禁。 原始契约：a durable configuration change that has not yet reached the running snapshots refuses this endpoint with 503 configuration_stale exactly as it refuses an inference call: the gate is the listener’s, ahead of the handler, and discovery is not exempt from it
POST /v1/moderations
- 请求头：
Authorization、Content-Type - 路径参数：无
- 正文或表单字段：
model、input - 响应字段：
id、model、results
POST /v1/rerank
- 请求头：
Authorization、Content-Type - 路径参数：无
- 正文或表单字段：
model、query、documents、top_n - 响应字段：
results - 本构建不可服务：唯一对应的 Provider Profile 被 withheld，无法新建 Deployment。
GET /v1/responses/{id}
- 请求头：
Authorization - 路径参数：
id - 正文或表单字段：无请求正文
- 响应字段：
id、object、created_at、completed_at、status、background、error、model、output、usage - 特有偏差：只有
background=true的提交可以按 ID 查询；同步 Response 不保存，不能事后调用 GET 找回。 原始契约：only a submission made with background=true is retrievable; a synchronous response is never stored - 特有偏差：轮询延迟 Response 时从
Retry-After响应头读取等待时间；不要在 Response JSON 中寻找轮询间隔。 原始契约：the polling cadence is carried in the Retry-After header rather than as a non-standard member of the Response object - 特有偏差：查询不调用上游、不写 Ledger，也不消耗计费 Project 限流或预算；轮询受固定 Key/Project 上限约束，超限返回 429 与
Retry-After。 原始契约：retrieval makes no upstream call, writes no ledger events, and consumes no per-Project rate limit or budget; polling is bounded by the fixed per-minute ceiling on the calling Key and on its Project, refused as 429 rate_limit_exceeded with Retry-After - 特有偏差：首次成功读取后 15 分钟或创建后 24 小时（取较早者）记录会删除；应用必须在窗口内持久化结果。 原始契约：the record is reaped 15 minutes after its first successful retrieval, or at its 24 hour TTL, whichever comes first
DELETE /v1/responses/{id}
- 请求头：
Authorization - 路径参数：
id - 正文或表单字段：无请求正文
- 响应字段：
id、object、deleted - 特有偏差：删除延迟 Response 会移除记录及密封对象，但不会撤销已经发生的费用；财务侧不得冲销对应 Attempt。 原始契约：deletion removes the record and both of its sealed objects; it does not undo accounting for work that already happened
- 特有偏差：删除延迟 Response 前先确认终态；仍欠结果的记录返回 409，必须先取消并轮询到终态。 原始契约：a submission still owed an answer answers 409: cancel it first
- 特有偏差：删除不消耗计费 Project 限流，但仍受与查询相同的固定 Key/Project 上限约束。 原始契约：deletion consumes no per-Project rate limit; it is bounded by the same fixed per-minute ceiling as retrieval
POST /v1/responses/{id}/cancel
- 请求头：
Authorization - 路径参数：
id - 正文或表单字段：无请求正文
- 响应字段：
id、object、created_at、completed_at、status、background、error、model、output、usage - 特有偏差：队列中的请求可确定取消；已运行请求只能尽力取消，必须轮询最终状态，并保留“上游可能已计费”的结果。 原始契约：cancelling a queued submission is determinate; cancelling one already running is best-effort and is settled conservatively, so the record says plainly that it may have been billed upstream
- 特有偏差：只对未完成的延迟请求调用取消；已终态请求返回 409，不能把该响应解释为取消成功。 原始契约：a request that has already finished answers 409 rather than pretending to cancel
- 特有偏差：取消不调用上游、不消耗计费 Project 限流，但仍受与查询相同的固定 Key/Project 上限约束。 原始契约：cancellation reaches no upstream and consumes no per-Project rate limit; it is bounded by the same fixed per-minute ceiling as retrieval
运行治理端点见客服工单闭环， 媒体端点见内容安全与媒体生成链， Files、Batches、Async 资源见资源生命周期。
需要最小请求、Halro-Route 请求头、幂等、轮询和当前构建可用性说明时，阅读 媒体、Files、Batches 与异步 API。
为什么合并成一页
Section titled “为什么合并成一页”按完整骨架把这 27 个端点各生成一页：平均每页 2.4 个请求字段、6.0 个响应字段，
sdk_matrix 全部未声明，profile_coverage 多为单个 Profile 且未声明任何限制。也就是说
27 个页面的主要内容会是免责声明本身。合并成这一页，信息密度反而更高。