DEVELOPERS

三步开始调用

登录后创建密钥，就能发出第一条请求。密钥只放在你自己的服务器上，不要写进网页。

curl -X POST "$STR_BASE/v1/chat/completions" \ ...

快速开始

创建密钥
注册登录后，打开「项目与密钥」，新建一把密钥。完整内容只会显示一次，请马上保存。
复制示例
把下方示例里的密钥换成你自己的。模型名称可以在模型详情页复制。
查看用量
调用成功后，打开「用量」或「账单」，就能看到这次花了多少、还剩多少。

鉴权

所有接口都使用 Authorization: Bearer <你的密钥> 进行鉴权。密钥与项目绑定，项目又归属于某个组织，一个组织下可以创建多个项目和密钥，方便按业务线拆分配额与权限。

密钥可以配置模型白名单和来源 IP 白名单；命中限制会直接返回 403，请在工作台确认密钥的允许范围。

请求示例

curl -X POST "$STR_BASE/v1/chat/completions" \
  -H "Authorization: Bearer 你的密钥" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"model":"str/demo-chat","messages":[{"role":"user","content":"你好"}]}'

写入类请求（如对话、生图、生视频）都必须携带 Idempotency-Key 请求头；网络抖动重试时，同一个键只会成功扣一次费，换成新内容请换一个新的键。

计费说明

调用按当时公布的价格记账，之后改价不影响已经产生的费用。余额不足或超过预算时调用会被拒绝（见下方 402 错误），请先充值或调整项目预算。模型未上架或渠道不可用时无法调用。工作台里的收据用于对账，不替代税务发票。

错误处理

出错时接口会返回统一的错误结构：{ error: { code, message, retryable, request_id } } 。下面是常见的 HTTP 状态码与错误码含义：

状态码	错误码	含义
400	`idempotency_key_required`	缺少 Idempotency-Key 请求头。所有写入类调用（如 chat/completions）都必须携带。
401	`invalid_api_key`	Authorization 头缺失、格式不对或密钥已失效/被撤销。
402	`insufficient_credit / budget_exceeded`	组织余额不足，或超过了项目/组织设置的月度预算。请先充值或调整预算。
403	`model_not_allowed / ip_not_allowed / trial_frozen`	密钥的模型或 IP 白名单不允许本次调用，或试用权益已被冻结/该模型不在试用范围内。
404	`task_not_found / video_not_available`	查询的异步任务（如视频生成）不存在，或产物已过期/不可用。
409	`idempotency_conflict`	同一个 Idempotency-Key 被用于内容不同的请求，需要换一个新的键重试。
429	`rate_limit_exceeded`	超过了密钥或所属范围的调用频率配额，请按退避策略重试。
503	`model_unavailable / storage_unavailable`	对应模型渠道或对象存储暂时不可用，通常可以直接重试。

错误体中的 retryable 字段标明该错误是否适合直接重试；出问题时可以带上request_id 联系我们排查。

常见问题

密钥泄露了怎么办？ 在「项目与密钥」页面立即撤销旧密钥并创建新的。

可以先试用再付费吗？ 可以，注册后领取试用额度，用完再按需充值。

调用失败会重复扣费吗？ 带上相同的 Idempotency-Key 重试同一次请求不会重复扣费。

接口和常见 SDK 兼容吗？ 接口兼容常见对话接口格式，可以直接复用你现有的 HTTP 客户端或社区 SDK，只需把请求地址和密钥换成本平台的即可。

需要更大额度或企业合同？ 请查看定价页的企业服务。