> ## Documentation Index
> Fetch the complete documentation index at: https://ppio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 常见问题

<Tip>
  在使用过程中遇到任何问题，欢迎随时[联系我们](https://ppio.com/contact)。
</Tip>

## 代金券使用指南

### PPIO 提供哪些类型的代金券？

PPIO 目前提供以下类型的代金券，帮助用户体验平台服务：

* **新用户代金券**：首次注册的用户可领取，用于试用各类模型服务。
* **邀请奖励代金券**：邀请他人注册并完成任务后获得。

## 模型速率限制（Rate Limits）

### 不同用户的 RPM 限制是多少？

RPM（每分钟请求数）限制根据用户的认证级别和账号状态有所不同。详细限制请参见[速率限制说明](/model/llm-rate-limits)。

<Tip>
  如需进一步协助，欢迎[联系我们](https://ppio.com/contact)。
</Tip>

## RPM 限速调整与升级规则

### 用户可以申请提高 RPM 限制吗？

可以。PPIO 支持根据使用需求灵活调整 RPM。规则如下：

* **DeepSeek 系列模型**：平台将尽力满足合理的扩容需求。
* **其他模型**：根据模型成本和用户实际使用情况综合评估，受资源可用性限制。

**申请流程：**

用户 → 客服 / 技术支持 → 产品团队审核 & 审批

### 实际用量低于承诺 RPM，会怎样处理？

如果用户实际 RPM 连续一周低于承诺值，平台将按以下规则调整：

* 将限制降至过去一周内的峰值 RPM，或
* 恢复到模型默认速率限制（取较低值）。

### 支持自助升级 RPM 吗？

支持。PPIO 计划推出 **RPM 升级包**，用户可自主管理和提升 RPM 限制，无需人工审批。

## API 调用相关问题

### GLM-4.5 如何关闭思考模式？

调用 `zai-org/glm-4.5` 时，如不需要思考模式，可在请求体中添加以下参数：

```python theme={null}
"enable_thinking": false
```

完整示例：

```python theme={null}
{
  "model": "zai-org/glm-4.5",
  "messages": [
    {
      "role": "user",
      "content": "北京今天天气怎么样？"
    }
  ],
  "temperature": 0.7,
  "stream": false,
  "max_tokens": 500,
  "enable_thinking": false
}
```

### 如何查看 DeepSeek 缓存命中情况？

调用 DeepSeek 模型时，响应体的 `usage` 字段会包含缓存命中信息：

```json theme={null}
{
  "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）：**

```python theme={null}
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}")
```

详细的监控指标查询请参见[模型 API 监控](/model/llm-api-metrics)。

### 调用返回 429 错误，如何处理？

`429 Too Many Requests` 表示请求频率超出当前 RPM 限制。处理方式：

1. **降低请求频率**：在客户端实现指数退避重试逻辑
2. **申请提高 RPM**：联系我们申请 RPM 升级，参见[RPM 升级规则](#rpm-限速调整与升级规则)
3. **使用批量推理**：对延迟不敏感的场景，使用[批量推理 API](/model/llm-batch-api) 规避限速

```python theme={null}
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 正确，可在[模型列表](/model/llm)查询        |
| `messages` 格式 | 必须为数组，每条消息包含 `role` 和 `content`          |
| 输入长度          | 不超过对应模型的 context window 限制               |
| 参数类型          | `temperature` 为 float，`max_tokens` 为 int |

### 调用返回 403 错误，如何处理？

`403 Forbidden` 常见原因及解决方案：

| 错误码 / 原因                | 触发条件                                 | 解决方案                                                                  |
| ----------------------- | ------------------------------------ | --------------------------------------------------------------------- |
| `NOT_ENOUGH_KEY_BUDGET` | API Key 设置了消费上限（Budget Limit），且额度已用尽 | 在[密钥管理页面](https://ppio.com/settings/key-management)调整或取消 Budget Limit |
| 账号余额不足                  | 账户余额耗尽                               | 前往[充值页面](https://ppio.com/billing/recharge)充值                         |
| 模型需要加白                  | 部分模型需申请访问权限                          | [联系我们](https://ppio.com/contact)提交申请                                  |
| 套餐限制                    | 所使用的模型不在当前套餐内                        | 切换模型或升级套餐                                                             |

### 模型响应很慢或内容被截断，怎么排查？

**响应慢：**

* 检查 `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，参见[模型列表](/model/llm)             |
| `429` | 请求过频   | 超出 RPM 限制                | 降低频率或申请升级 RPM                            |
| `500` | 服务端错误  | 平台内部异常                   | 重试，持续问题请[联系我们](https://ppio.com/contact) |
| `503` | 服务不可用  | 模型过载或维护中                 | 稍后重试，建议指数退避                              |

## 第三方客户端集成

### 如何在 Cursor 等第三方工具中使用 PPIO？

PPIO API 完全兼容 OpenAI 接口规范，可在支持自定义 Base URL 的第三方客户端中使用，配合 PPIO 提供的开源模型（如 DeepSeek、Qwen、GLM 等）。

**通用配置：**

```text theme={null}
Base URL: https://api.ppio.com/openai
API Key:  您的 PPIO API Key
模型名称: 如 deepseek/deepseek-v3.2-exp、qwen/qwen3-235b 等
```

**Cursor 配置注意事项：**

1. 模型名称必须与[模型列表](/model/llm)完全一致（区分大小写）
2. 添加自定义模型后，请**取消勾选其他默认模型**
3. Base URL 末尾**不要多加斜杠**
4. 点击 SAVE 后点击 Verify 验证连通性

**已知支持自定义 Base URL 的客户端：**

* Chatbox（桌面客户端，适合新手）
* NextChat / ChatGPT-Next-Web（网页版，可自部署）
* Open WebUI（功能丰富，支持多模型）
* LobeChat（界面美观，功能全面）

详细的集成指南请参见对应工具的专题文档（如 [Cursor 集成指南](/third-party/cursor-use)）。

### 能否在 ChatGPT（chatgpt.com）中使用 PPIO API Key？

不可以。**官方 ChatGPT 网页版（chatgpt.com）不支持自定义 API Key**，只能使用 OpenAI 自有服务。

如需类 ChatGPT 体验配合 PPIO 模型，请使用上一节列出的第三方客户端，效果一致。

## 图像与视频生成常见问题

### 视频生成任务失败，如何排查？

常见失败原因及解决方案：

| 失败类型    | 可能原因               | 解决方案                        |
| ------- | ------------------ | --------------------------- |
| 任务排队超时  | 高峰期队列拥塞            | 稍后重试，或在非高峰时段提交              |
| 提示词违规   | 含违禁内容              | 修改提示词，避免暴力、色情等违规内容          |
| 图片格式不支持 | 不支持的图片格式或尺寸        | 转换为 JPEG/PNG，分辨率建议 512px 以上 |
| 参数超出范围  | duration/fps 等参数超限 | 参考对应模型的 API 文档调整参数          |
| 账户余额不足  | 余额耗尽任务被终止          | 充值后重新提交                     |

### 视频生成 API 如何配置超时时间？

视频生成为异步任务，建议使用轮询方式查询任务状态，并设置合理的超时时间：

```python theme={null}
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）")
```

<Note>
  不同模型的生成时长差异较大（30 秒到 10 分钟不等），建议根据模型文档设置合理的 `max_wait`。
</Note>

### 图像 URL 有哪些要求？

使用图像 URL 作为输入时，需满足以下要求：

* **可公开访问**：URL 必须可被平台服务器直接访问，不支持需要登录或 Cookie 的地址
* **格式支持**：JPEG、PNG、WebP
* **大小限制**：建议单张图片不超过 10 MB
* **分辨率**：建议 512px × 512px 及以上，过小可能影响生成质量
* **有效期**：确保 URL 在任务处理期间持续有效（建议使用永久链接或有效期 ≥ 1 小时的预签名 URL）

<Warning>
  如果图片存储在私有存储桶，请生成带有足够有效期的预签名 URL，或将图片上传至公开可访问的 CDN。
</Warning>