常见问题

注册与账户

注册需要什么资料？

注册必须填写账户名、手机号、短信验证码和密码，并通过 Turnstile 人机验证。邮箱当前不在注册页面展示；后续如需绑定邮箱，可在账户设置中维护。

可以多人共用一个账户吗？

不推荐。当前版本采用单账户 + 多 API Key 模型：建议按环境或服务拆分 Key， 用 Key 的过期时间、速率限制、Token 上限和预算上限控制风险。审计日志记录当前账号自己的重要操作。

注册后有免费额度吗？

当前采用余额按量计费，不再按月赠送固定 token。注册后可以先充值小额余额， 再用 API Key 或 Playground 验证上游模型。

接入与调用

我的代码可以直接从 OpenAI 切过来吗？

可以。Swarmix 兼容 OpenAI /v1/chat/completions 调用方式。通常只需改 2 处：api_key 和 base_url。高级参数、多模态输入和模型能力以具体厂商文档为准。 详细步骤见 OpenAI SDK 集成指南。

能同时调用多个厂商的模型吗？

可以。把 model 参数换成对应的模型 ID 即可。同一把 API Key 可以自由调用平台上所有你有权限的模型。

支持 Embedding / 图像生成 / TTS 吗？

目前只支持 Chat Completions。Embedding / Image / Audio / Video 在路线图上。

为什么我请求失败了但日志里没显示？

请求必须通过鉴权层（有效 Key）才会进入请求日志。如果连 401 都拿到，说明 Key 错了。检查：

• Key 有没有拷贝完整（sk-swx- 开头，长度 32+）
• 在 Console → API Keys 里 Key 是不是仍显示为"活跃"
• base URL 是不是 /v1 结尾

计费与账单

token 怎么计算？

严格按照 OpenAI tokenizer 的结果。每次响应的 usage 字段返回准确的 prompt_tokens / completion_tokens。Swarmix 按这两个数字 × 单价扣款。

我没有调用成功也扣款了吗？

不会。上游返回 4xx/5xx 或当前模型没有可用上游候选时，0 扣款。 有一种例外：流式请求已经返回部分 token，此时按实际已产生的 token 结算。

为什么余额扣了但日志里看不到？

ClickHouse 的请求明细有 1-2 秒的延迟。MySQL 的交易流水是实时的。可以在账单 & 充值 页查 transactions 表，那里立即能看到扣款。

可以开发票吗？

当前 Console 已提供充值和交易流水查询。发票流程尚未做成自助页面，如需开票请通过工单提交公司抬头、税号和充值记录。

故障与排障

请求 504 超时怎么办？

上游厂商偶发。Swarmix 会按当前 retry 策略做有限重试，仍失败则透传给客户端。客户端侧建议实现指数退避重试 —— 见 重试最佳实践。

流式响应卡在某个位置不动了？

通常是上游模型的 TTFT（首 token）还没到，或正在"思考"。给客户端设合理的读超时（建议 30-60s）， 命中后当作失败重试。长推理模型（deepseek-reasoner）可能首 token 要 5-15 秒。

返回结果和 OpenAI 不一样？

Swarmix 路由到的是国产厂商模型，能力和风格会有差异。建议：

• 调 temperature / top_p 适应国产模型风格
• prompt 增加明确的格式约束（国产模型更吃 few-shot）
• 用 deepseek-reasoner 替代需要复杂推理的场景

安全

我的 API Key 泄露了怎么办？

立即去 Console 删除。 5 分钟内全球所有副本失效。查审计日志确认泄露期间的异常请求，如有异常扣款发工单申诉。

Swarmix 会看到我的 prompt 内容吗？

内容会经过平台的请求链路（审核模块可选，需主动开启），但不会被记录到长期存储里用于任何训练或分析。 原始请求日志只保留 90 天用于故障排查，长期趋势使用聚合统计；请求体只在 debug 模式下保留摘要。具体见隐私政策。

可以关闭内容审核吗？

内容审核属于平台侧可选安全模块，是否启用取决于当前部署配置。当前客户 Console 不提供自助开关； 如需调整策略请提交工单。