代金券使用指南
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 数（按标准输入价格计费）
调用返回 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 错误，如何处理？
常见原因及解决方案：
- 账号余额不足 → 前往充值页面充值后重试
- 模型需要加白 → 部分模型需申请访问权限，请联系我们提交申请
- 套餐限制 → 所使用的模型可能不在当前套餐内
模型响应很慢或内容被截断，怎么排查？
响应慢：
- 检查
stream 参数：设置 "stream": true 可立即获得首个 token，改善感知延迟
- 检查网络连通性：国内访问建议使用
api.ppinfra.com 端点
- 思考模型（如 DeepSeek-R1）推理阶段耗时较长，属正常行为
内容被截断：
- 检查
max_tokens 设置：默认值可能较小，根据任务需要适当调大
- 检查响应的
finish_reason：
stop：正常结束length：触发 max_tokens 上限，需调大该值
错误排查
常用错误码速查
| 错误码 | 含义 | 常见原因 | 解决方案 |
|---|
400 | 请求格式错误 | 参数类型/格式有误、输入超长 | 检查参数格式和输入长度 |
401 | 认证失败 | API Key 无效或已过期 | 检查 API Key 是否正确 |
403 | 访问被拒绝 | 余额不足、模型未加白、套餐限制 | 充值或申请模型权限 |
404 | 资源不存在 | 模型 ID 错误 | 检查模型 ID，参见模型列表 |
429 | 请求过频 | 超出 RPM 限制 | 降低频率或申请升级 RPM |
500 | 服务端错误 | 平台内部异常 | 重试，持续问题请联系我们 |
503 | 服务不可用 | 模型过载或维护中 | 稍后重试，建议指数退避 |
图像与视频生成常见问题
视频生成任务失败，如何排查？
常见失败原因及解决方案：
| 失败类型 | 可能原因 | 解决方案 |
|---|
| 任务排队超时 | 高峰期队列拥塞 | 稍后重试，或在非高峰时段提交 |
| 提示词违规 | 含违禁内容 | 修改提示词，避免暴力、色情等违规内容 |
| 图片格式不支持 | 不支持的图片格式或尺寸 | 转换为 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。
