代金券使用指南
PPIO 提供哪些类型的代金券？
PPIO 目前提供以下类型的代金券，帮助用户体验平台服务：
- 新用户代金券：首次注册的用户可领取，用于试用各类模型服务。
- 邀请奖励代金券：邀请他人注册并完成任务后获得。
模型速率限制（Rate Limits）
不同用户的 RPM 限制是多少？
RPM（每分钟请求数）限制根据用户的认证级别和账号状态有所不同。详细限制请参见速率限制说明。
RPM 限速调整与升级规则
用户可以申请提高 RPM 限制吗？
可以。PPIO 支持根据使用需求灵活调整 RPM。规则如下：
- DeepSeek 系列模型：平台将尽力满足合理的扩容需求。
- 其他模型：根据模型成本和用户实际使用情况综合评估，受资源可用性限制。
申请流程：
用户 → 客服 / 技术支持 → 产品团队审核 & 审批
实际用量低于承诺 RPM，会怎样处理？
如果用户实际 RPM 连续一周低于承诺值，平台将按以下规则调整：
- 将限制降至过去一周内的峰值 RPM，或
- 恢复到模型默认速率限制（取较低值）。
支持自助升级 RPM 吗？
支持。PPIO 计划推出 RPM 升级包，用户可自主管理和提升 RPM 限制，无需人工审批。
API 调用相关问题
GLM-4.5 如何关闭思考模式？
调用 zai-org/glm-4.5 时，如不需要思考模式，可在请求体中添加以下参数：
完整示例：
{
"model": "zai-org/glm-4.5",
"messages": [
{
"role": "user",
"content": "北京今天天气怎么样？"
}
],
"temperature": 0.7,
"stream": false,
"max_tokens": 500,
"enable_thinking": false
}
如何查看 DeepSeek 缓存命中情况？
调用 DeepSeek 模型时，响应体的 usage 字段会包含缓存命中信息：
{
"usage": {
"prompt_tokens": 1000,
"completion_tokens": 200,
"total_tokens": 1200,
"prompt_cache_hit_tokens": 800,
"prompt_cache_miss_tokens": 200
}
}
prompt_cache_hit_tokens：命中缓存的 token 数（按缓存读取价格计费，约为标准输入价格的 1/10）prompt_cache_miss_tokens：未命中缓存的 token 数（按标准输入价格计费）
如何查看 API 调用记录？
PPIO LLM API 属于无状态接口，平台本身不会保存每次请求的完整对话内容。控制台主要提供：
- 账单与 Token 用量统计
- API Key 的调用次数等聚合数据
如需查看完整对话历史，建议在应用层自行记录每次 API 响应中的 usage 字段。
代码示例（Python）：
from openai import OpenAI
client = OpenAI(
base_url="https://api.ppio.com/openai",
api_key="<Your API Key>",
)
response = client.chat.completions.create(
model="<your-model-id>",
messages=[{"role": "user", "content": "你好"}],
)
# 获取本次调用的 token 用量
usage = response.usage
print(f"输入 tokens: {usage.prompt_tokens}")
print(f"输出 tokens: {usage.completion_tokens}")
调用返回 429 错误，如何处理？
429 Too Many Requests 表示请求频率超出当前 RPM 限制。处理方式：
- 降低请求频率：在客户端实现指数退避重试逻辑
- 申请提高 RPM：联系我们申请 RPM 升级，参见RPM 升级规则
- 使用批量推理：对延迟不敏感的场景，使用批量推理 API 规避限速
import time, random
def call_with_retry(fn, max_retries=5):
for attempt in range(max_retries):
try:
return fn()
except Exception as e:
if "429" in str(e) and attempt < max_retries - 1:
wait = (2 ** attempt) + random.uniform(0, 1)
time.sleep(wait)
else:
raise
调用返回 400 错误，如何处理？
常见原因：
- 输入长度超出模型上下文窗口限制
- 参数类型或格式错误
- 请求体缺少必填字段
请检查以下项目：
| 检查项 | 说明 |
|---|
model 字段 | 确认模型 ID 正确，可在模型列表查询 |
messages 格式 | 必须为数组，每条消息包含 role 和 content |
| 输入长度 | 不超过对应模型的 context window 限制 |
| 参数类型 | temperature 为 float，max_tokens 为 int |
调用返回 403 错误，如何处理？
403 Forbidden 常见原因及解决方案：
| 错误码 / 原因 | 触发条件 | 解决方案 |
|---|
NOT_ENOUGH_KEY_BUDGET | API Key 设置了消费上限（Budget Limit），且额度已用尽 | 在密钥管理页面调整或取消 Budget Limit |
| 账号余额不足 | 账户余额耗尽 | 前往充值页面充值 |
| 模型需要加白 | 部分模型需申请访问权限 | 联系我们提交申请 |
| 套餐限制 | 所使用的模型不在当前套餐内 | 切换模型或升级套餐 |
模型响应很慢或内容被截断，怎么排查？
响应慢：
- 检查
stream 参数：设置 "stream": true 可立即获得首个 token，改善感知延迟
- 检查网络连通性：国内访问建议使用
api.ppinfra.com 端点
- 思考模型（如 DeepSeek-R1）推理阶段耗时较长，属正常行为
内容被截断：
- 检查
max_tokens 设置：默认值可能较小，根据任务需要适当调大
- 检查响应的
finish_reason：
stop：正常结束length：触发 max_tokens 上限，需调大该值
错误排查
常用错误码速查
| 错误码 | 含义 | 常见原因 | 解决方案 |
|---|
400 | 请求格式错误 | 参数类型/格式有误、输入超长 | 检查参数格式和输入长度 |
401 | 认证失败 | API Key 无效或已过期 | 检查 API Key 是否正确 |
403 | 访问被拒绝 | 余额不足、Key 预算用尽、模型未加白、套餐限制 | 充值或申请模型权限 |
404 | 资源不存在 | 模型 ID 错误 | 检查模型 ID，参见模型列表 |
429 | 请求过频 | 超出 RPM 限制 | 降低频率或申请升级 RPM |
500 | 服务端错误 | 平台内部异常 | 重试，持续问题请联系我们 |
503 | 服务不可用 | 模型过载或维护中 | 稍后重试，建议指数退避 |
第三方客户端集成
如何在 Cursor 等第三方工具中使用 PPIO？
PPIO API 完全兼容 OpenAI 接口规范，可在支持自定义 Base URL 的第三方客户端中使用，配合 PPIO 提供的开源模型（如 DeepSeek、Qwen、GLM 等）。
通用配置：
Base URL: https://api.ppio.com/openai
API Key: 您的 PPIO API Key
模型名称: 如 deepseek/deepseek-v3.2-exp、qwen/qwen3-235b 等
- 模型名称必须与模型列表完全一致（区分大小写）
- 添加自定义模型后，请取消勾选其他默认模型
- Base URL 末尾不要多加斜杠
- 点击 SAVE 后点击 Verify 验证连通性
已知支持自定义 Base URL 的客户端：
- Chatbox（桌面客户端，适合新手）
- NextChat / ChatGPT-Next-Web（网页版，可自部署）
- Open WebUI（功能丰富，支持多模型）
- LobeChat（界面美观，功能全面）
详细的集成指南请参见对应工具的专题文档（如 Cursor 集成指南）。
能否在 ChatGPT（chatgpt.com）中使用 PPIO API Key？
不可以。官方 ChatGPT 网页版（chatgpt.com）不支持自定义 API Key，只能使用 OpenAI 自有服务。
如需类 ChatGPT 体验配合 PPIO 模型，请使用上一节列出的第三方客户端，效果一致。
图像与视频生成常见问题
视频生成任务失败，如何排查？
常见失败原因及解决方案：
| 失败类型 | 可能原因 | 解决方案 |
|---|
| 任务排队超时 | 高峰期队列拥塞 | 稍后重试，或在非高峰时段提交 |
| 提示词违规 | 含违禁内容 | 修改提示词，避免暴力、色情等违规内容 |
| 图片格式不支持 | 不支持的图片格式或尺寸 | 转换为 JPEG/PNG，分辨率建议 512px 以上 |
| 参数超出范围 | duration/fps 等参数超限 | 参考对应模型的 API 文档调整参数 |
| 账户余额不足 | 余额耗尽任务被终止 | 充值后重新提交 |
视频生成 API 如何配置超时时间？
视频生成为异步任务，建议使用轮询方式查询任务状态，并设置合理的超时时间：
import time
def poll_task(task_id, client, max_wait=600, interval=10):
"""轮询视频任务结果，最长等待 600 秒"""
elapsed = 0
while elapsed < max_wait:
result = client.get_task(task_id)
status = result.get("status")
if status == "succeeded":
return result
elif status == "failed":
raise Exception(f"任务失败: {result.get('error')}")
time.sleep(interval)
elapsed += interval
raise TimeoutError(f"任务 {task_id} 超时（{max_wait}s）")
不同模型的生成时长差异较大（30 秒到 10 分钟不等），建议根据模型文档设置合理的 max_wait。
图像 URL 有哪些要求？
使用图像 URL 作为输入时，需满足以下要求：
- 可公开访问：URL 必须可被平台服务器直接访问，不支持需要登录或 Cookie 的地址
- 格式支持：JPEG、PNG、WebP
- 大小限制：建议单张图片不超过 10 MB
- 分辨率：建议 512px × 512px 及以上，过小可能影响生成质量
- 有效期：确保 URL 在任务处理期间持续有效（建议使用永久链接或有效期 ≥ 1 小时的预签名 URL）
如果图片存储在私有存储桶，请生成带有足够有效期的预签名 URL，或将图片上传至公开可访问的 CDN。
