API 技术FAQ

401 错误表示未授权（Unauthorized），服务端无法验证请求身份。

常见原因及排查：

1. API Key 复制错误：复制时可能含多余空格、换行或不完整。建议在代码中使用环境变量存储，避免手动复制。
2. 密钥已被重置或删除：登录后进入 「API 密钥」 页面查看密钥状态是否为「可用」。如已失效，创建新密钥替换。
3. Authorization 格式错误：正确格式为 Authorization: Bearer sk-xxxxxxxx，注意 Bearer 后面有空格、sk- 前缀不能省略。
4. 使用了错误的 base_url：确认请求的 API 端点地址正确，参考 API 文档。

429 Too Many Requests 表示请求频率超过账户速率限制。

当前限制：

• 普通用户：每分钟 60 次请求
• 企业套餐用户：每分钟 300 次请求
• 高并发通道：联系商务单独配置（可达 1000+ 次/分钟）

解决方法（按推荐顺序）：

1. 代码中加入请求间隔：在连续请求之间加入 50-200ms 延迟（time.sleep(0.1)）
2. 实现速率控制算法：使用令牌桶（Token Bucket）或漏桶算法管理并发
3. 升级套餐：升级到企业套餐可提升至每分钟 300 次
4. 联系商务提额：如需大量并发调用（如批量处理场景），联系商务经理开通专用高并发通道

429 错误 不扣 token 费用。

503 Service Unavailable 表示后端模型服务暂时不可用。

常见原因：

• 上游模型供应商（OpenAI / Anthropic / Google 等）正在进行计划性维护
• 上游服务出现突发波动
• 算力小仓平台正在进行计划性维护（会提前在公告栏通知）

处理方式：

• 平台会自动重试请求，通常几秒到几分钟内恢复
• 在代码中实现指数退避重试（Exponential Backoff），避免频繁失败
• 如持续超过 5 分钟，可切换到同类备选模型（如 GPT-4o 不可用时用 Claude 3.5）
• 关注 API 中转 页面的模型可用状态

503 错误不会扣除任何 token 费用。

Token ≠ 字符数/字数，这是正常现象。

Token 与字数的换算关系（大约）：

• 中文：1 个汉字 ≈ 1.5-2 个 token（因为中文分词粒度更细）
• 英文：1 个单词 ≈ 1-2 个 token（短词 1 token，长词可能拆成多个）
• 标点、空格、换行：也会计入 token

Token 计费范围：

• 包含 输入 token（你发送的 Prompt、系统消息、历史对话）
• 包含 输出 token（模型生成的回复）
• 输入和输出通常不同价（输出价格更高），详见 「API 中转」 各模型详情

如需精确计算 token 数，可使用 OpenAI 官方 tiktoken 工具或各模型的在线 tokenizer 计算器。

设置步骤：

1. 登录后进入 「API 密钥」 管理页面
2. 找到目标密钥，点击 「设置额度」
3. 设置每日消费上限（元）和/或 每月消费上限（元）
4. 保存设置，立即生效

额度预警：

• 消费达到 80% 时：发送站内信提醒
• 消费达到 90% 时：发送站内信 + 邮件提醒
• 消费达到 100%：该密钥调用自动暂停，返回错误信息

建议为生产环境密钥设置合理的日额度上限，测试环境密钥设置较低的额度，避免意外超额消费。

完全支持。算力小仓提供标准 OpenAI 兼容接口。

已兼容的开源项目：

• OneAPI / NewAPI：在渠道管理中添加类型为 OpenAI 的渠道，填入算力小仓的 API endpoint 和 Key 即可
• ChatGPT-Next-Web：在设置中填入自定义接口地址和 API Key
• LobeChat：在模型供应商中选择 OpenAI，填入自定义 endpoint
• OpenCat / ChatBox：添加自定义 API 提供商
• 任何支持自定义 base_url 的 OpenAI SDK（Python、Node.js、Go 等）

对接配置参数：

• API Base URL：见 「API 中转」 页面
• API Key：你的算力小仓密钥（sk- 开头）
• 支持流式输出（Stream = true）
• 支持 Function Calling / Tools 调用

对接步骤：

1. 登录 Dify 管理后台
2. 进入 「设置」→「模型供应商」
3. 点击 「添加供应商」，选择 「OpenAI-API-compatible」
4. 填写配置：
   • 供应商名称：算力小仓（自定义即可）
   • API Base URL：见 「API 中转」 页面
   • API Key：你的算力小仓密钥（sk- 开头）
5. 点击「保存」
6. 在创建 Dify 应用时，模型列表中将显示算力小仓提供的所有模型

支持的功能：

• Chat 对话模型（GPT-4o、Claude、Gemini、DeepSeek 等）
• Embedding 向量模型
• Rerank 重排序模型
• 流式输出（Streaming）

三个查看渠道：

1. API 中转 页面：每个模型卡片直接显示输入/输出 token 单价（元/百万 token），一目了然。
2. API 文档：完整的计费表和每个模型的详细说明（支持参数、上下文长度、功能特性等）。
3. 调用日志：查看每次实际请求的扣费明细，实际感受不同模型的成本差异。

计费特点：

• 输入和输出通常分别计价（输出价格通常是输入的 2-4 倍）
• 高级模型（GPT-4o、Claude 3.5）比基础模型（GPT-4o-mini、Gemini Flash）贵 10-20 倍
• 算力小仓的 API 中转价格通常低于官方定价

建议根据任务复杂度选择模型：复杂推理用高级模型，简单对话和分类任务用基础模型可大幅节省成本。

完全支持国内外多地域接入。

国内接入：

• 国内专属接入域名，服务器部署在国内多节点
• 直连访问，无需代理/翻墙
• 国内用户可获得毫秒级低延迟

海外接入：

• 提供海外接入点，海外用户使用可获得更低延迟
• 平台自动选择最优路由节点
• 开发者无需手动切换域名

具体接入地址请参考 API 文档 或 「API 中转」 页面。

批量并发优化方案：

1. 控制并发数

• 普通用户：控制在 10 个并发以内
• 企业用户：控制在 20 个并发以内
• 使用信号量（Semaphore）或线程池控制并发数

2. 使用异步框架

• Python：httpx.AsyncClient + asyncio.Semaphore(10)
• Go：goroutine + buffered channel
• Node.js：分批执行 Promise.all

3. 实现指数退避重试

• 第 1 次失败 → 等待 1 秒后重试
• 第 2 次失败 → 等待 2 秒后重试
• 第 3 次失败 → 等待 4 秒后重试
• 最多重试 3 次

4. 请求间隔

• 连续请求间加入 50-100ms 间隔

如需 100+ 并发，联系商务开通高并发专用通道。

登录后进入 「调用日志」 页面，可查看所有 API 调用记录。

每条日志包含以下信息：

• 请求时间（精确到毫秒）
• 模型名称
• 使用的 API 密钥 ID（可区分不同项目）
• 输入 token 数量 + 输出 token 数量
• 扣费金额（精确到小数点后 4 位）
• 响应状态码和耗时（ms）
• 错误信息（401/429/503 等错误的具体原因）

筛选功能：支持按时间范围、模型名称、密钥 ID、状态码（2xx/4xx/5xx）多维度筛选。

支持 导出为 Excel 格式，便于财务对账和用量分析。日志保留期为 90 天。

绘画 API 生成时间通常为 10-30 秒，复杂图片可能更长。

优化建议：

1. 设置合理的超时时间：客户端请求超时建议设置为 120 秒（而非默认的 30 秒）
2. 降低图片分辨率：从 1024×1024 降到 768×768 或 512×512 可显著加快生成速度
3. 减少生成数量：单次请求生成 1 张而非多张
4. 避开高峰期：工作日上午和晚上通常是调用高峰
5. 使用更快的模型：部分绘画模型（如 Flux Schnell）比标准模型快得多

绘画 API 的超时请求不扣费，可以安全重试，不会造成重复扣费。

Suno 音乐 API 排查步骤：

1. 检查请求参数：
   • prompt（音乐描述）：建议使用英文，描述音乐风格、情绪、乐器等
   • duration（时长）：整数秒数，需在模型支持范围（通常 30-300 秒）
   • tags（风格标签）：须在 Suno 支持的标签列表中选择
2. 查看调用日志：在日志中查看具体错误码和错误描述
3. Suno 服务波动：Sunos API 偶尔不稳定，遇到 503 等待 30 秒后重试
4. 联系客服：如持续失败（连续 5 次以上），联系客服反馈完整请求参数和日志截图

失败调用不扣费。建议在代码中实现自动重试逻辑，避免人工干预。

默认注册后可以调用所有公开模型的 API。

限制模型权限的方法：

• 子账号管理：在 「子账号管理」 中为每个子账号设置可调用的模型白名单，仅允许指定模型。
• 密钥白名单：在 「API 密钥」 管理页面，为单个密钥设置可调用的模型范围（如只允许 GPT-4o-mini 和 DeepSeek V3）。
• 企业定制：联系商务为企业账户定制模型权限方案（如屏蔽某类模型、只开放国产模型等）。

模型白名单是安全保障和成本控制的重要手段，建议团队按实际需要设置。

设置步骤：

1. 登录后进入 「API 密钥」 管理页面
2. 选择目标密钥，找到 「IP 白名单」 设置区域
3. 添加允许调用的 IP 地址，支持以下格式：
   • 单个 IPv4：192.168.1.100
   • CIDR 网段：10.0.0.0/24（允许整个 C 段的 256 个 IP）
   • IPv6：2001:db8::1
4. 点击保存，立即生效

白名单规则：

• 不在白名单内的 IP 发起的请求返回 403 Forbidden
• 可不添加任何白名单 = 不限制（默认状态）
• 不同密钥可设置不同的白名单
• 建议生产环境密钥必须绑定白名单

企业客户可申请私有化 API 部署。

私有化部署的优势：

• 独立实例资源，性能不受其他用户影响
• 专属 API 域名
• 自定义限流策略和并发配额
• 独立资源池，保证高并发下的稳定性
• 数据完全隔离

申请流程：

1. 联系商务经理说明技术需求和部署环境
2. 双方技术评估（约 2-3 个工作日）
3. 签订合同
4. 部署实施（通常 2-4 周，复杂需求可能更长）
5. 测试验收后正式上线

适合对数据安全、性能稳定性有高要求的中大型企业。具体费用和方案请联系商务获取报价。

强烈建议区分测试和生产环境的密钥。

推荐配置：

• 测试密钥：备注「测试环境」，日额度 5 元，仅开放基础模型
• 生产密钥：备注「生产环境」，日额度根据业务量设置，开放全部所需模型

为什么需要区分：

• 测试代码 bug 可能导致疯狂调用，低额度密钥自动熔断
• 分别监控两个环境的用量和成本
• 生产密钥泄露时重置不会影响测试环境
• 方便成本分析（区分研发和生产开销）

在 「API 密钥」 页面点击「创建密钥」即可新建，建议至少创建 2 个分别使用。

接口返回乱码通常是客户端编码问题。

排查步骤：

1. 检查请求头：设置 Content-Type: application/json; charset=utf-8
2. 检查响应解码：确保客户端使用 UTF-8 解码 HTTP 响应体（Python 中 response.content.decode("utf-8")）
3. 用 curl 测试：如果 curl 返回正常而代码中乱码，确认是代码编码问题
4. Windows 特别注意：Windows 控制台默认使用 GBK 编码，可能无法正确显示 UTF-8 内容（可设置 chcp 65001 切换到 UTF-8）

如果以上方法仍无法解决，请在调用日志中查看原始请求和响应内容，联系客服提供截图协助排查。

支持开具增值税发票。

开票条件：

• 企业用户需完成实名认证（提交营业执照）
• 开票金额须累计满 100 元
• 需填写完整的开票信息（抬头、税号、地址、电话等）

发票类型：

• 增值税电子普通发票：企业和个人均可申请，发送至注册邮箱
• 增值税专用发票（纸质）：仅企业用户可申请，顺丰快递寄出

开票流程：在 「账单」→「申请开票」 页面提交申请 → 审核（1-2 个工作日）→ 开具（审核通过后 3-5 个工作日）。详情也可参考 充值账单 FAQ。

只有返回 HTTP 200 成功响应的请求才扣费。

以下情况均不扣费：

• 4xx 客户端错误：401（未授权）、429（限流）、400（参数错误）等
• 5xx 服务端错误：500（服务器内部错误）、503（服务不可用）等
• 请求超时：客户端设置的超时时间内未收到响应
• 网络中断：请求发送失败或连接断开

验证方法：在 「调用日志」 页面筛选非 200 状态的记录，这些条目的扣费金额应为 0。

因此失败调用可以安全重试，不会造成重复扣费。