网络与安全

• 全部接口通过 HTTPS 提供，不要在客户端关闭证书校验（TLS 校验保持开启）
• Key 通过 Authorization: Bearer 头传递，不要放进 URL 查询参数
• 网关会拒绝查询参数形式的密钥，返回认证错误

只走 443 端口，全部 TLS，不需要开放其他端口：

流式响应用的是长连接，中间代理如果有「空闲超时」设置，要调到 5 分钟以上，否则长回答会被中途切断。

• All endpoints are served over HTTPS; never disable certificate verification on the client (keep TLS verification on)
• Keys travel in the Authorization: Bearer header, never in URL query parameters
• The gateway rejects keys passed as query parameters with an authentication error

Only port 443 is used, all over TLS; no other ports need to be opened:

Streaming responses use long-lived connections. If an intermediate proxy has an idle timeout, raise it to 5 minutes or more, otherwise long answers get cut off mid-stream.

• 网关只转发请求与响应，不修改模型输入与输出，也不会注入与业务无关的内容
• 请求内容会转发到对应的上游模型厂商
• 用量记录保存请求的元数据：时间、Key 标识、模型、token 数、费用、耗时与状态，用于计费与排障
• 请求与响应正文仅用于完成本次调用
• 生成结果的 URL 有有效期，过期后自动失效

• The gateway only forwards requests and responses; it doesn't modify model input or output, and doesn't inject unrelated content
• Request content is forwarded to the corresponding upstream model vendor
• Usage records store request metadata — time, key identifier, model, token counts, cost, duration, and status — for billing and troubleshooting
• Request and response bodies are used only to complete that call
• Generated result URLs expire and stop working after that

• Key 只在创建时完整显示一次，之后只能看到前缀，丢了就重新建一把
• 不要写进代码。用环境变量或密钥管理服务，前端代码里的 Key 等于公开
• 不要提交进仓库。把 .env 加进 .gitignore；已经提交过的，光删掉不够，历史记录里还在，必须轮换
• 按环境分开。开发、测试、生产各用各的 Key，一个泄露不影响其他
• 定期轮换，尤其是有人员变动时。轮换前先建新 Key 并切换，确认稳定后再删旧的
• 服务端集成建议用固定出口 IP，便于在控制台配置白名单
• 发给他人或嵌入前端的 Key，建议单独创建并设置额度上限，出问题可以单独吊销

泄露了怎么办：

1. 立刻在控制台删除泄露的 Key
2. 建新 Key 替换到各处
3. 查用量接口，看泄露期间有没有异常调用
4. 检查代码历史，确认没有其他硬编码

删除是立即生效的，但已经发生的调用费用不会退还，只能从用量记录里追查范围。

• A key is shown in full only once at creation; afterwards you can only see the prefix. If you lose it, create a new one
• Don't hardcode it. Use environment variables or a secret manager; a key in front-end code is effectively public
• Don't commit it to a repository. Add .env to .gitignore; if it's already been committed, deleting it isn't enough — it's still in history, so rotate it
• Separate by environment. Use different keys for development, testing, and production so a leak in one doesn't affect the others
• Rotate regularly, especially when staff change. Create the new key, switch over, confirm it's stable, then delete the old one
• Server-side integrations should use a fixed egress IP so you can configure an allowlist in the console
• For keys handed to others or embedded in a front end, create them separately with their own limit so you can revoke one without affecting the rest

If a key leaks:

1. Delete the leaked key in the console immediately
2. Create a new key and replace it everywhere
3. Check the usage endpoint for abnormal calls during the leak window
4. Check your code history for other hardcoded keys

Deletion takes effect immediately, but charges for calls that already happened aren't refunded; you can only trace the scope from usage records.

• 用强密码，不要与其他站点复用
• 定期在控制台检查「令牌」列表，删掉不再使用的 Key
• 开启低余额提醒，异常消耗能更早发现
• 团队协作时按人分 Key，不要共用一个，便于追溯

• Use a strong password you don't reuse on other sites
• Periodically review the "Tokens" list in the console and delete keys you no longer use
• Turn on low-balance alerts so abnormal consumption shows up early
• When collaborating, give each person their own key instead of sharing one, so usage is traceable

企业内网如果走统一出口，需要放行 api.oairoute.com 与 ark.oairoute.com 的 443 出站流量。

如果用的是 HTTP 代理，注意流式请求可能被缓冲，表现为「等了很久然后一次性吐出全部内容」。解决方式是在代理配置里对这两个域名关闭响应缓冲。

If your corporate network routes through a single egress point, allow outbound 443 traffic to api.oairoute.com and ark.oairoute.com.

With an HTTP proxy, note that streaming requests may get buffered, which looks like "a long wait, then everything arrives at once". Fix it by disabling response buffering for those two domains in the proxy configuration.

超时设置：客户端超时建议不低于 60 秒。长文生成与推理模型耗时更久，建议按场景放宽。流式模式按事件间隔判断超时，而不是按总时长——有数据持续返回就说明连接正常。

自建服务可以参考这组配置：

重试策略：遇到 429 按 Retry-After 等待，不要立即重试，详见错误码与限流。

Timeout settings: client timeouts should be at least 60 seconds. Long-form generation and reasoning models take longer, so relax it by scenario. In streaming mode, judge timeouts by the gap between events rather than total duration — data still arriving means the connection is fine.

For your own services, this configuration is a reasonable starting point:

Retry strategy: on 429, wait for Retry-After instead of retrying immediately; see Error codes and rate limits.

需要审计能力时，在自己的服务侧记录每次调用的：

• 调用时间与耗时
• 使用的模型与 Key 标识
• 输入输出 token 数
• 状态码与错误类型

平台侧的用量接口能提供聚合数据，但细到单条请求的记录要在自己的网关层留。

If you need auditability, log the following for each call on your own side:

• Call time and duration
• Model used and key identifier
• Input and output token counts
• Status code and error type

The platform's usage endpoint provides aggregate data, but per-request records need to be kept in your own gateway layer.

发现漏洞或可疑行为，请发送邮件到 [email protected]，我们会尽快处理。请附上复现步骤与影响范围，不要在公开渠道披露细节。

If you find a vulnerability or suspicious behavior, email [email protected] and we'll address it promptly. Include reproduction steps and impact scope, and please don't disclose details publicly.