分销商 API 密钥与客户

通过 OneProvider 分销商 API 创建、充值、暂停和删除客户的 API 密钥并管理客户，每个调用都附 curl 示例。

通过分销商 API 发放、充值、暂停和删除客户密钥，并管理您的客户，附 curl 示例。

全部模型、功能与价格面向 AI 智能体的文档索引： https://oneprovider.dev/docs/llms.txt

密钥对象

密钥字段

字段	说明
`id`	不透明的已签名标识符，不是数字。
`name`, `customer_label`	密钥名称和客户标记（例如昵称）。
`customer_id`	密钥所属的客户，或 null。
`tail`	密钥的末尾字符，便于识别。
`status`	`active`, `paused`, `expired`, `deleting`
`limit_usd`	售出总额：已用加剩余。
`spent_usd`, `remaining_usd`	已用和剩余。
`expires_at`, `created_at`	到期时间和创建时间（UTC）。永久有效的密钥（由带 expires_never 的套餐或带 key_expires_never 的兑换码批次生成）expires_at 为 null。
`last_used_at`	目前始终为 null。
`concurrency`	并行请求数上限（1 到 1000），随密钥保存，目前尚未强制执行。
`dashboard_url`	给您客户的中立仪表板链接。它不是密钥本身。

发放密钥

POST /keys（权限 keys；必须带 Idempotency-Key 请求头）。必填：name 和 limit_usd；可选：expires_days（1..365，默认 30）或 expires_hours（1 到 8760，例如 1 表示一小时的密钥；二者不能同时使用）、customer_id、customer_label、concurrency。

bash

curl -s -X POST https://app.oneprovider.dev/partner/v1/keys \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: key-anna-001" \
-H "Content-Type: application/json" \
-d '{"name":"anna-main","limit_usd":"25.00","expires_days":30,"customer_label":"Anna"}'
# a one-hour key
curl -s -X POST https://app.oneprovider.dev/partner/v1/keys -H "Authorization: Bearer $OP_PARTNER_TOKEN" -H "Idempotency-Key: key-trial-001" -H "Content-Type: application/json" -d '{"name":"trial","limit_usd":"1.00","expires_hours":1}'

一次发放多个相同的密钥：POST /keys/bulk，带上 count（1..50）、name_prefix，以及相同的 limit_usd、expires_days/expires_hours。密钥会命名为 {name_prefix}-1 … {name_prefix}-N。系统会先检查总额 count × limit_usd；如果调用中途仍然中断，请带上相同的 Idempotency-Key 重复调用：已生成的密钥会再次返回，其余的会继续发放。

json

{
"id": "<key id>",
"name": "anna-main",
"customer_label": "Anna",
"status": "active",
"limit_usd": "25.00",
"spent_usd": "0.00",
"remaining_usd": "25.00",
"expires_at": "2026-11-07T12:00:00Z",
"dashboard_url": "<dashboard link>",
"key": "sk-..."
}

密钥只显示一次 key 字段只出现在发放响应（201）中，以及用相同 Idempotency-Key 对该调用做的完全相同的重复请求中。请立即把它交给您的客户并保存：之后无法再取回密钥，丢失后只能发放新密钥。其他任何响应（GET、列表）或 Webhook 都不含密钥。

密钥的额度会在分销商余额上预留。如果超出“可用”（Free，即 available_usd），响应为 409 insufficient_balance；名称重复返回 409 name_taken，密钥数量达到上限返回 409 key_limit。

列表与读取

bash

# active keys of one customer
curl -s "https://app.oneprovider.dev/partner/v1/keys?status=active&customer_id=<customer id>&limit=50" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"
# one key (no secret) with dashboard_url
curl -s https://app.oneprovider.dev/partner/v1/keys/<key id> \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

筛选：status、query（按名称和标记搜索）、customer_id。按天和按模型的用量：GET /keys/{id}/usage?days=30（权限 read，时间窗口 1 到 90 天，默认 30）。响应为 {"key_id", "days", "items": [{"day", "spend_usd", "requests", "tokens"}], "models": [{"model", "spend_usd", "requests", "tokens"}]}：UTC 日期连续无缺口（包含为零的日子），金额与个人中心用量页上的数字一致，tokens 包括 input、output、cache_read、cache_write。某个客户全部有效密钥的用量：GET /customers/{id}/usage（响应含 keys，最多读取 100 个密钥，以及 truncated）。服务商故障时返回 503 provider_unavailable。

编辑、充值、暂停

bash

# change the limit / expiry / name / label / concurrency
curl -s -X PATCH https://app.oneprovider.dev/partner/v1/keys/<key id> \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"limit_usd":"40.00"}'
# add 10.00 USD to the key limit
curl -s -X POST https://app.oneprovider.dev/partner/v1/keys/<key id>/topup \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: topup-anna-001" \
-H "Content-Type: application/json" \
-d '{"amount_usd":"10.00"}'
# pause and resume
curl -s -X POST https://app.oneprovider.dev/partner/v1/keys/<key id>/pause -H "Authorization: Bearer $OP_PARTNER_TOKEN"
curl -s -X POST https://app.oneprovider.dev/partner/v1/keys/<key id>/resume -H "Authorization: Bearer $OP_PARTNER_TOKEN"

PATCH 中的 limit_usd 是新的总额度；不能低于已消耗的金额（400 limit_below_spent）。与新密钥一样，提高额度时增加的部分必须在“可用”（Free）范围内。调低额度会立即把未使用的差额退回“可用”。暂停时预留金额保持不变。有效期：expires_days/expires_hours 把它设为现在 + N，extend_days/extend_hours 在当前有效期上增加 N（已过期则从现在起算；已过期的密钥会重新预留其剩余额度，这部分必须在“可用”范围内）；两者不能同时使用，且到期时间不得超过 8760 小时之后。带上可选的 Idempotency-Key 时，重复的 extend_* 只会延长一次。永久有效的密钥（expires_at = null）没有可延长的有效期：extend_* 不适用，而 expires_* 会为它设定期限。已封禁客户的密钥只接受 name 和 customer_label，其他任何修改都返回 409 customer_blocked。

删除密钥

bash

curl -s -X DELETE https://app.oneprovider.dev/partner/v1/keys/<key id> \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

密钥立即删除时，响应为 200 {"state":"deleted"}；删除仍在进行时为 202 {"state":"deleting"}。额度中未使用的部分会立即退回“可用”。

重新发放密钥

POST /keys/{id}/rotate（权限 keys；必须带 Idempotency-Key 请求头）：为同一位客户生成新的密钥，例如旧密钥泄露时。旧密钥会立即失效。未使用的余额和有效期会转移到新密钥。

bash

curl -s -X POST https://app.oneprovider.dev/partner/v1/keys/<key id>/rotate \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: rotate-anna-001"

这是一个带有新 id 的新密钥：已消耗的历史留在旧密钥（现已删除）上。201 响应包含密钥对象、key（新密钥，只显示一次）和 rotated_from（旧密钥的 id）。错误：404 key_not_found、409 key_limit、key_exhausted（已无余额）、key_expired（已过期：请先延长有效期）、503 provider_unavailable。

客户

客户就是您的买家。密钥、订单和兑换码都可以关联到某个客户：您自己的标识符保存在 external_id 中（唯一，最多 64 个字符）。

bash

curl -s -X POST https://app.oneprovider.dev/partner/v1/customers \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"external_id":"user-77","name":"Anna","note":"from the Telegram shop"}'
curl -s "https://app.oneprovider.dev/partner/v1/customers?external_id=user-77" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

客户对象：id、external_id、name、note、blocked、keys_count、created_at。用 PATCH /customers/{id} 修改 name 和 note。重复的 external_id 返回 409 customer_exists。

封禁客户

bash

curl -s -X PATCH https://app.oneprovider.dev/partner/v1/customers/<customer id> \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"blocked":true}'

封禁（权限 keys）会暂停该客户所有有效的密钥，并将该客户标记为 blocked: true。为其发放密钥、下订单和兑换码都会返回 409 customer_blocked。解封（{"blocked":false}）只会恢复被封禁暂停的密钥：您自己暂停的密钥仍保持暂停。

最后更新: 2026-11-08 发现问题？ @Oneproviderhelpbot