PixVerse API 接入：独立平台、端点与积分

PixVerse 有官方 REST API，而且它不是消费端那个产品。请求都发到 https://app-api.pixverse.ai，每次调用带两个请求头，生成是异步的，积分按秒计。

三个名字，加一套独立积分

先把三个面切开。PixVerse 是消费端站点。PixVerse Platform 是 API 产品，控制台在 platform.pixverse.ai，文档在 docs.platform.pixverse.ai。app-api.pixverse.ai 才是请求域名，模型层面的信息汇总在 PixVerse 主题总览页。

这个切分一直切到钱包。订阅页开头就是两条警告：API 会员与 PixVerse Web 会员是两套，且 API 积分不能用在 PixVerse Web 上。网页端套餐不会抬高 API 的上限，而 API 套餐的升降级官方写的是暂不支持。

这条 API 里没有的那条路

实时世界模型 PixVerse R1 不是模型选择器里的取值。它的 API 走合作申请：720p 输出、集成音频、最长 300 秒连续生成。自助接入的是 V6 与 C1。

鉴权需要两个请求头

两个必填头

API-KEY 放控制台里创建的密钥，官方写明只显示一次。Ai-trace-id 必须是每次请求都唯一的 UUID。复用这件事官方写得很硬：同一个 Ai-trace-id 用两次，就不会生成新视频。它也是官方点名的「任务卡在生成中」第一原因。

密钥从哪里来

在控制台创建 app key；已有 PixVerse 消费端账号可以直接登录。控制台是客户端渲染的，所以文档才是唯一可读的记录。Recraft 的密钥只要一个 Bearer 头，这也正是第二个 PixVerse 头容易踩空的原因。

第一条请求：从提交到下载

三步走完一个生命周期：提交任务、留下返回的 video_id、轮询它，最后从 url 下载。网页端上手指南讲的是同一件事在控制台里怎么做。

# 需要 curl 与 jq。每次请求都要生成一个新的 Ai-trace-id。
curl --request POST 'https://app-api.pixverse.ai/openapi/v2/video/text/generate' \
  --header "API-KEY: ${PIXVERSE_API_KEY}" \
  --header 'Ai-trace-id: 6f1c2d3a-9b74-4c1e-8f2a-0d5e7c9b1a34' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "aspect_ratio": "16:9",
    "duration": 5,
    "model": "v6",
    "motion_mode": "normal",
    "prompt": "A matte black smart speaker sits on a walnut desk at sunrise",
    "quality": "720p",
    "seed": 0,
    "water_mark": false
  }'
# => {"ErrCode":0,"ErrMsg":"success","Resp":{"video_id":123456}}

# 轮询到状态从 5 变成 1，再读 `url`。
curl --request GET 'https://app-api.pixverse.ai/openapi/v2/video/result/123456' \
  --header "API-KEY: ${PIXVERSE_API_KEY}" \
  --header 'Ai-trace-id: 9d7b52c0-1e46-4a83-b0f5-2c94e6d8a310'

响应外壳固定是 ErrCode、ErrMsg、Resp。决定账单的是 quality、duration 和 generate_audio_switch 三个参数；音频默认 false，aspect_ratio 只用于文生视频与 Fusion。

图生视频：先上传换 img_id

图生视频是两次调用。先把图片上传，响应返回一个 img_id；生成调用送的是这个 ID，不是 URL。上传接口返回的两个字段是 img_id 与 img_url，生成接口只认前者。支持 png、webp、jpeg、jpg，最大 10000 像素，官方建议至少 1024×1024。

# 第一步：上传图片并取回 img_id。
curl --location --request POST 'https://app-api.pixverse.ai/openapi/v2/image/upload' \
  --header "API-KEY: ${PIXVERSE_API_KEY}" \
  --header 'Ai-trace-id: 3a8f1d64-5b2e-4c70-9a11-7f0d8e2b4c65' \
  --form 'image=@"storyboard.png"'
# => {"ErrCode":0,"ErrMsg":"success","Resp":{"img_id":98765,"img_url":"..."}}

# 第二步：带着同样的两个请求头把这个 img_id 送出去。
curl --location --request POST 'https://app-api.pixverse.ai/openapi/v2/video/img/generate' \
  --header "API-KEY: ${PIXVERSE_API_KEY}" \
  --header 'Ai-trace-id: 0c4d9a17-6e83-4b52-8d29-1a5f3b7c9e02' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "duration": 5,
    "img_id": 98765,
    "model": "v6",
    "motion_mode": "normal",
    "prompt": "The camera pushes in slowly, warm light across the rim",
    "quality": "720p",
    "seed": 0
  }'

把文件路径当成 img_id 传会拿到 400032，图片超限会拿到 500030。

端点全景、状态与错误码

生成类接口都在 https://app-api.pixverse.ai/openapi/v2/ 下，用 model 参数选 v6 或 c1。

视频续写是唯一一条硬性能力差：只有 V6 支持；其余能力各自独立，各有自己的端点、入参要求和计费，文档不把它们并进生成类的参数表。

C1 承载分镜这条路：静态分镜板会被转成连续序列，所以上面这张六格图就是模型要读的输入形态。

结果状态

状态是响应体里的数字，不是 HTTP 码：5 等待、1 成功、7 内容审核失败、8 生成失败。url 只在状态 1 时可取，被过滤的视频会自动退还积分，所以状态 7 不花钱。

会改客户端代码的错误码

500090 是余额不足。500071 表示所选特效不支持 720p 或 1080p。400018/400019 把提示词长度限制在 2048 字符——这与模型页冲突，V6 和 C1 写的都是 5000。在官方对齐之前，按低的那条留余量。

限的是并发数，不是每分钟请求数

限流页没有公开任何每分钟请求数，只公开同时生成的任务数，官方叫 Concurrent Requests。官方对这条限制的定义是「同时生成任务的最大数量」，并按会员档位给出不同数值。

超限返回 500044（reached the limit for concurrent generations），官方给的解法是升级套餐，或发邮件到 api@pixverse.ai。

# 把 500044 当成背压、而不是硬失败来处理的提交函数。
submit() {
  response=$(curl -s --request POST \
    "https://app-api.pixverse.ai/openapi/v2/video/text/generate" \
    --header "API-KEY: ${PIXVERSE_API_KEY}" \
    --header "Ai-trace-id: $(uuidgen)" \
    --header 'Content-Type: application/json' \
    --data-raw "$1")
  if [ "$(echo "$response" | jq -r '.ErrCode')" = "500044" ]; then
    echo "concurrency ceiling reached, backing off" >&2
    sleep 10
    submit "$1"
    return
  fi
  echo "$response" | jq -r '.Resp.video_id'
}

积分按输出秒数计

生成按秒计价，不是按次计价，单价取决于分辨率和是否生成音频。

C1 在每个档位都比 V6 贵 1 分每秒。带 video_references 的 Fusion 调用单价翻倍，V6 1080p 无音频从 18 变成 36。官方另有一条：遗留模型把 motion_mode 设为 fast 时，积分消耗翻倍。定价页只给了一条货币换算：$1 = 5 videos (v6, 720p, 5s, no audio, with Starter pack)。各档美元价格与每月积分总量官方未公布。另一家厂商的视频模型，可以看我们的 Seedance 笔记。

API 侧的输出权利不等于网页端条款

同一个品牌有两套条款、两个运营主体，在商用输出上口径不同，两套条款的更新时间也相差近四个月。

所以「PixVerse 的输出只能非商用」不是安全的总结。API 条款禁止的是转售接口本身：售卖调用服务、把 API 集成进第三方应用转卖、或搭一个镜像服务。

常见问题

网页端积分能用在 API 上吗？ 不能。API 会员与网页端会员是两套，API 积分也不能用在 PixVerse Web 上。

为什么任务一直停在生成中？ 几乎总是 Ai-trace-id 被复用；每次生成都要换一个新 UUID。

积分不够会怎样？ API 返回 500090。各档套餐总量与美元价格官方未公布。

审核失败会扣积分吗？ 不会。状态 7 是内容审核失败，这部分积分会自动退还。

官方公布了每分钟请求上限吗？ 没有。限的是同时生成任务数，Free 3 到 Business 25，超限返回 500044。

密钥在 API 平台创建，把 500044 当成背压处理。

发布于

2026年9月14日

信息核验

2026年9月14日

作者

AI Tool Blog 编辑部