PixVerse API 常见问题 — 接入、认证、速率、错误处理

接入前

我的 API Key 应该怎么生成

在 PixVerse Web 端：个人设置 → API Key 管理 → 创建新 Key。

创建后立即复制保存——Key 只在创建时完整显示一次，之后只能在控制台看到部分遮罩。丢了只能删除重建。

API Credits 和 Web 订阅 Credits 是同一个吗

通常不是。API 调用消耗的是 API Credits（需要单独购买），Web 界面消耗的是订阅套餐里的 Credits。两者独立计费、独立账户。以实际为准。

哪个模型通过 API 可以调用

API 支持的模型和 Web 端基本一致——V6、V5.6、V5、V5.5 等。可用模型列表可能变化，以最新 API 文档为准。

认证相关

每次请求都要带 AI-Trace-ID 吗

是的。PixVerse API 要求每个请求都携带 AI-Trace-ID Header，用于问题追踪。用 UUID 生成即可：

import uuid
trace_id = str(uuid.uuid4())

返回 401 Unauthorized 怎么办

检查：

1. App-Key Header 是否存在且正确
2. Key 有没有被删除或过期
3. 有没有多复制空格或换行符

返回 403 Forbidden 怎么办

Key 有权限限制——可能你的 Key 没有某个端点的权限，或者订阅等级不够。联系官方升级权限。

速率限制

遇到 429 Too Many Requests 怎么办

这是 API 限流了。处理方法：

1. 等待：通常限流窗口是分钟级，等 1-5 分钟再试
2. 降低并发：同时进行的请求数量减少
3. 加重试逻辑：指数退避重试（每次等的时间翻倍）
4. 升级方案：更高等级的 API Credits 可能有更高的速率限制

import time

def safe_call(api_func, max_retries=5):
    for attempt in range(max_retries):
        try:
            return api_func()
        except Exception as e:
            if "429" in str(e) or "rate" in str(e).lower():
                wait = 60 * (2 ** attempt)  # 1min, 2min, 4min, ...
                print(f"限流，等待 {wait} 秒后重试...")
                time.sleep(wait)
            elif attempt == max_retries - 1:
                raise
    return None

批量生成的建议并发数

建议从 3-5 个并发开始测试，根据实际速率限制调整。不要一次开几十上百个并发——很容易触发限流。

状态轮询

应该多久查一次状态

建议 10 秒一次，这是比较合理的间隔：

• 不要 1 秒一次——太频繁，触发限流
• 不要 30 秒以上——可能错过完成时机，浪费时间

长时间停在 PROCESSING 怎么办

正常现象——视频生成需要时间。V6 + 1080P + 15 秒的视频可能需要 1-2 分钟。建议设置一个超时时间（比如 5 分钟），超时后再考虑是否重新提交。

状态变成 FAILED 了

先看 error_message 字段，通常会告诉你失败原因：

• prompt too short → 提示词太短
• content policy violation → 触发内容安全策略
• insufficient credits → Credits 不足

修复后重新提交即可。如果连续失败，联系官方支持。

下载相关

下载 URL 是临时的吗

是的，API 返回的下载 URL 通常有有效期（可能几小时到一天）。建议生成完成后尽快下载，不要等太久。

下载速度慢怎么办

可以：

1. 用支持断点续传的下载工具（curl -C -、wget -c）
2. 从下载 URL 判断是否可以用并行下载
3. 考虑自己搭一个下载中转服务

下载的视频文件打不开

可能是下载不完整。重新下载，确认文件大小和 API 返回的元数据一致。还是不行的话，重新生成。

图生视频相关

图片应该用什么格式

推荐 JPG 或 PNG。避免 BMP、TIFF、HEIC 等格式——API 可能不支持或自动转换出问题。

图片太大怎么办

• 压缩图片到 5MB 以内（Base64 方式建议）
• 或用 URL 方式上传大图到自己的 CDN

URL 方式的图片加载不出来

确保：

1. URL 是公网可访问的（不要用 localhost、内网地址、需要认证的地址）
2. 图片支持 HTTPS
3. 图片服务器没有防盗链限制

调试技巧

先在 Web 界面调通 prompt 再写 API

Web 界面可以快速试错 prompt、看效果、选参数。Web 上确认效果没问题了，再把同样的 prompt 和参数搬到 API 里——避免在 API 层面反复试错浪费 Credits。

保存每个请求的 Trace ID

API 问题排查时，官方支持团队会问你 Trace ID。每次调用都记录下来，出问题能快速定位。

先跑最小化测试

第一次接入 API 时，先用最简单的参数跑通一条完整流程：

# 最小化测试
generate(prompt="一只猫", model="v5", duration=5, resolution="720p")

跑通后再逐步加参数、改模型、加并发。