BYOK

概览

基础路径: https://api.infrai.cc/v1/byok

鉴权头: Authorization: Bearer $INFRAI_API_KEY

bash

# Call any /v1/byok capability over raw HTTP — no SDK to install.
# curl:
curl https://api.infrai.cc/v1/byok/... \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json"

方法

byok.register

POST /v1/byok/register

注册供应商凭证，以通过你自己的密钥分发调用。

参数

名称	类型	必填	说明
`provider`	`ByokProvider \| string`	必填	供应商 provider id，例如 openai。
`alias`	`string`	必填	你为该凭证选择的标签。
`credentials`	`Record<string, string>`	必填	供应商凭证字段（只写）。
`idempotency_key`	`string`	可选	可选去重 key；相同重试将返回同一结果。

ByokKey { byok_id, provider, alias, state, created_at, test_result? }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/byok/register \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "module": "ai-runtime", "api_key": "sk-..."}'

byok.list

GET /v1/byok/list

列出你已注册的 BYOK 凭证。

{ items: ByokKey[] }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/byok/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

byok.test

POST /v1/byok/test/{id}

测试某个 BYOK 凭证的连通性。

参数

名称	类型	必填	说明
`id`	`string`	必填	BYOK 凭证 id。

{ ok, latency_ms?, error? }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/byok/test/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

byok.revoke

DELETE /v1/byok/revoke/{id}

吊销某个 BYOK 凭证。

参数

名称	类型	必填	说明
`id`	`string`	必填	BYOK 凭证 id。

{ ok: boolean }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X DELETE https://api.infrai.cc/v1/byok/revoke/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

byok.get

GET /v1/byok/get/{id}

获取单个 BYOK 凭证的配置详情，包括 provider、状态与绑定列表。

参数

名称	类型	必填	说明
`id`	`string`	必填	BYOK 凭证 ID。

ByokConfig { byok_id, provider, label?, state, bindings[], created_at }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/byok/get/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

byok.update

PATCH /v1/byok/update/{id}

更新 BYOK 凭证的元数据（如 label），不重新注册、不改动密钥。模块绑定请用 bind 管理。

参数

名称	类型	必填	说明
`id`	`string`	必填	BYOK 凭证 ID。
`label`	`string`	可选	该凭证的新可读名称。
`idempotency_key`	`string`	可选	可选去重 key；相同重试将返回同一结果。

ByokConfig { byok_id, provider, label?, state, bindings[] }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X PATCH https://api.infrai.cc/v1/byok/update/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

byok.enable

POST /v1/byok/enable/{id}

启用此 BYOK 凭证，使其重新参与路由。

参数

名称	类型	必填	说明
`id`	`string`	必填	BYOK 凭证 ID。
`idempotency_key`	`string`	可选	可选去重 key；相同重试将返回同一结果。

ByokConfig { byok_id, state, bindings[] }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/byok/enable/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

byok.disable

POST /v1/byok/disable/{id}

停用此 BYOK 凭证，停止经其路由但不删除。

参数

名称	类型	必填	说明
`id`	`string`	必填	BYOK 凭证 ID。
`idempotency_key`	`string`	可选	可选去重 key；相同重试将返回同一结果。

ByokConfig { byok_id, state, bindings[] }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/byok/disable/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

byok.bind

POST /v1/byok/bind/{id}

将凭证绑定到某个 capability 或 module（可选锁定到具体 model），路由按最具体优先匹配；capability/module 至少传一个。

参数

名称	类型	必填	说明
`id`	`string`	必填	BYOK 凭证 ID。
`capability`	`string`	可选	要绑定的能力，例如 'ai.chat'。
`module`	`string`	可选	要绑定的模块，例如 'ai-runtime'。
`model`	`string`	可选	可选，在绑定范围内锁定的模型。
`idempotency_key`	`string`	可选	可选去重 key；相同重试将返回同一结果。

ByokConfig { byok_id, bindings[] }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/byok/bind/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

byok.unbind

POST /v1/byok/unbind/{id}

移除一个绑定；capability/module 至少传一个。返回含 bindings 的 BYOK 配置。

参数

名称	类型	必填	说明
`id`	`string`	必填	BYOK 凭证 ID。
`capability`	`string`	可选	要解绑的能力，例如 'ai.chat'。
`module`	`string`	可选	要解绑的模块，例如 'ai-runtime'。
`idempotency_key`	`string`	可选	可选去重 key；相同重试将返回同一结果。

ByokConfig { byok_id, bindings[] }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/byok/unbind/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

byok.policy.get

GET /v1/byok/policy/get

读取当前账户的 BYOK 路由策略（byok_only / byok_then_pool 及可选 scope）。

ByokPolicy { mode, scope? }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/byok/policy/get \
  -H "Authorization: Bearer $INFRAI_API_KEY"

byok.policy.set

POST /v1/byok/policy/set

设置 BYOK 路由策略：byok_only 永不回退共享池，byok_then_pool 在 BYOK 失败时回退；scope 可缩小到某能力或模块。

参数

名称	类型	必填	说明
`mode`	`'byok_only' \| 'byok_then_pool'`	必填	byok_only=永不回退共享池；byok_then_pool=BYOK 失败时回退。
`scope`	`{ capability?: string; module?: string }`	可选	可选缩小范围；省略时为账户级。
`idempotency_key`	`string`	可选	可选去重 key；相同重试将返回同一结果。

ByokPolicy { mode, scope? }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/byok/policy/set \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "byok_only"}'

byok.quota.set

POST /v1/byok/quota/set/{id}

为单个 BYOK 凭证设置花费/调用上限，防止失控用量。

参数

名称	类型	必填	说明
`id`	`string`	必填	BYOK 凭证 ID。
`spend_limit_usd`	`number`	可选	花费上限（美元），最小为 0。
`call_limit`	`number`	可选	调用次数上限，最小为 0。
`window`	`'1d' \| '7d' \| '30d' \| 'mtd' \| 'ytd'`	可选	配额重置窗口，与 UsageInfo.period 词表一致（1d/7d/30d/mtd/ytd）。
`idempotency_key`	`string`	可选	可选去重 key；相同重试将返回同一结果。

ByokConfig { byok_id, quota? }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/byok/quota/set/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

byok.usage

GET /v1/byok/usage/{id}

查询单个 BYOK 凭证的用量（花费、调用次数、周期）。

参数

名称	类型	必填	说明
`id`	`string`	必填	BYOK 凭证 ID。

ByokUsage { byok_id, spend_usd, call_count, period }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/byok/usage/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

byok.events

GET /v1/byok/events/{id}

分页读取某个 BYOK 凭证的事件流（注册、轮换、绑定变更等）。

参数

名称	类型	必填	说明
`id`	`string`	必填	BYOK 凭证 ID。
`cursor`	`string`	可选	分页游标，用于获取下一页。
`limit`	`number`	可选	单页返回的最大条数。

{ items: ByokEvent[], next_cursor? }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/byok/events/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

byok.rotate

POST /v1/byok/rotate/{id}

原地替换密钥，保留 byok_id 与全部绑定，并触发 byok.rotated webhook。

参数

名称	类型	必填	说明
`id`	`string`	必填	BYOK 凭证 ID。
`api_key`	`string`	必填	新的明文厂商密钥；落库时信封加密，永不返回。
`idempotency_key`	`string`	可选	可选去重 key；相同重试将返回同一结果。

ByokConfig { byok_id, state, bindings[] }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/byok/rotate/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "..."}'

byok.rotate.stage

POST /v1/byok/rotate/stage/{id}

暂存一个候选密钥并探测其可用性，但不切换流量；之后用 rotate.commit 提交。

参数

名称	类型	必填	说明
`id`	`string`	必填	BYOK 凭证 ID。
`api_key`	`string`	必填	候选明文厂商密钥；落库时信封加密，永不返回。
`idempotency_key`	`string`	可选	可选去重 key；相同重试将返回同一结果。

{ stage_id, probe_result? }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/byok/rotate/stage/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "..."}'

byok.rotate.commit

POST /v1/byok/rotate/commit/{id}

将暂存的候选密钥提升为生效并切换流量，返回 BYOK 配置。

参数

名称	类型	必填	说明
`id`	`string`	必填	BYOK 凭证 ID。
`stage_id`	`string`	必填	byok.rotate.stage 返回的暂存句柄。
`idempotency_key`	`string`	可选	可选去重 key；相同重试将返回同一结果。

ByokConfig { byok_id, state, bindings[] }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/byok/rotate/commit/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stage_id": "..."}'

全部能力

本模块全部已路由能力——完整的对外 REST 契约。上方方法是带讲解的入门示例,此表是完整参考。

能力	端点	说明
`byok.bind`	`POST /v1/byok/bind/{id}`	Bind a BYOK credential to a capability or module (optionally pinning a model); most-specific match wins.
`byok.disable`	`POST /v1/byok/disable/{id}`	Disable a BYOK credential, halting routing through it without deleting it.
`byok.enable`	`POST /v1/byok/enable/{id}`	Re-enable a BYOK credential so it rejoins routing.
`byok.events`	`GET /v1/byok/events/{id}`	Page through the event stream for a single BYOK credential.
`byok.get`	`GET /v1/byok/get/{id}`	Retrieve configuration for one BYOK credential (provider, status, bindings).
`byok.list`	`GET /v1/byok/list`	List the bring-your-own-vendor (BYOK) credentials registered on this account.
`byok.policy.get`	`GET /v1/byok/policy/get`	Read the account's BYOK routing policy.
`byok.policy.set`	`POST /v1/byok/policy/set`	Set the BYOK routing policy (byok_only or byok_then_pool, optionally scoped).
`byok.quota.set`	`POST /v1/byok/quota/set/{id}`	Set a spend or call-count limit on a single BYOK credential.
`byok.register`	`POST /v1/byok/register`	Register a bring-your-own vendor credential (provider, api_key) on the account; idempotent.
`byok.revoke`	`DELETE /v1/byok/revoke/{id}`	Revoke a BYOK credential; idempotent.
`byok.rotate`	`POST /v1/byok/rotate/{id}`	Replace a BYOK secret in place, preserving the credential ID and all bindings.
`byok.rotate.commit`	`POST /v1/byok/rotate/commit/{id}`	Promote the staged candidate secret to active and switch traffic over to it.
`byok.rotate.stage`	`POST /v1/byok/rotate/stage/{id}`	Stage and probe a candidate secret without switching traffic to it.
`byok.test`	`POST /v1/byok/test/{id}`	Test whether a BYOK credential is working; idempotent.
`byok.unbind`	`POST /v1/byok/unbind/{id}`	Remove a capability or module binding from a BYOK credential.
`byok.update`	`PATCH /v1/byok/update/{id}`	Update BYOK credential metadata (e.g. label) without changing the secret or re-registering.
`byok.usage`	`GET /v1/byok/usage/{id}`	Query usage (spend, call count, period) for a single BYOK credential.

完整示例

本模块的生产级端到端范例:先一次性配置,再运行业务流程,尽量覆盖本模块的多数 API。

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

# 1) Auth: every call is a raw HTTPS request to the Infrai gateway carrying
#    only your project key. No SDK, no install.
#    Get your key: sign in with Google/GitHub at the console for a project key
#    + $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
#    POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."   # from the console


# 2) byok.register
curl -X POST https://api.infrai.cc/v1/byok/register \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "module": "ai-runtime", "api_key": "sk-..."}'

# 3) byok.list
curl -X GET https://api.infrai.cc/v1/byok/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

# 4) byok.test
curl -X POST https://api.infrai.cc/v1/byok/test/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# 5) byok.revoke
curl -X DELETE https://api.infrai.cc/v1/byok/revoke/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

# 6) byok.get
curl -X GET https://api.infrai.cc/v1/byok/get/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

# 7) byok.update
curl -X PATCH https://api.infrai.cc/v1/byok/update/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# 8) byok.enable
curl -X POST https://api.infrai.cc/v1/byok/enable/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# 9) byok.disable
curl -X POST https://api.infrai.cc/v1/byok/disable/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'