PixVerse API Platform 概览 — 企业级视频生成 API

什么是 API Platform

PixVerse API Platform 是面向开发者的RESTful API——你可以在自己的后端服务中通过 HTTP 请求调用 PixVerse 的全部能力，实现：

• 批量视频生成：一次生成几十上百个视频
• 业务系统集成：把 AI 视频生成嵌入自己的 SaaS、电商、内容平台
• Web 应用开发：开发自己的 PixVerse 前端或集成到现有前端
• 数据流水线：AI 视频作为数据处理流程的一环

API 和 CLI 底层用的是同一个服务，区别只是调用入口不同：CLI 适合单机脚本，API 适合服务端集成。

核心端点

根据 PixVerse 官方 Platform Docs，主要端点包括：

视频生成类

状态查询

账户类

认证机制

API Key

所有请求必须携带 App-Key 在 HTTP Header 中：

App-Key: pixverse_xxxxxxxxxxxxxxxxxxxx

AI-Trace-ID

官方文档提到每个请求还需要 AI-Trace-ID，这是一个唯一标识符用于问题追踪。通常可以用 UUID：

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

调用流程

PixVerse 视频生成的标准流程是异步的：

1. POST /generate → 返回 video_id（提交任务）
2. GET /status/{video_id} → 轮询直到状态变为完成
3. GET /download/{video_id} → 获取视频 URL，下载文件

状态流转

PENDING (5) → PROCESSING (4) →  ↓
                                SUCCESS (1) ✅
                                FAILED (2) ❌
                                TIMEOUT (3) ⏰

官方文档提到：当状态从 5（PENDING）变为 1（SUCCESS）时，可以通过 URL 下载视频文件。

示例：文生视频（Python）

import requests
import uuid
import time

API_KEY = "pixverse_your_api_key_here"
BASE_URL = "https://app-api.pixverse.ai"

def generate_text_to_video(prompt, model="v6", duration=8):
    # 1. 提交生成任务
    response = requests.post(
        f"{BASE_URL}/openapi/v2/video/text/generate",
        headers={
            "App-Key": API_KEY,
            "AI-Trace-ID": str(uuid.uuid4()),
            "Content-Type": "application/json"
        },
        json={
            "prompt": prompt,
            "model": model,
            "duration": duration,
            "aspect_ratio": "16:9",
            "resolution": "1080p"
        }
    )
    
    if response.status_code != 200:
        raise Exception(f"提交失败：{response.text}")
    
    video_id = response.json()["video_id"]
    print(f"任务已提交，video_id = {video_id}")
    
    # 2. 轮询状态
    while True:
        status_resp = requests.get(
            f"{BASE_URL}/openapi/v2/video/status/{video_id}",
            headers={
                "App-Key": API_KEY,
                "AI-Trace-ID": str(uuid.uuid4())
            }
        )
        status = status_resp.json()["status"]
        print(f"当前状态：{status}")
        
        if status == 1:  # SUCCESS
            break
        elif status in (2, 3):  # FAILED or TIMEOUT
            raise Exception(f"生成失败：{status_resp.json()}")
        
        time.sleep(10)  # 每 10 秒查一次
    
    # 3. 获取下载地址
    download_resp = requests.get(
        f"{BASE_URL}/openapi/v2/video/download/{video_id}",
        headers={
            "App-Key": API_KEY,
            "AI-Trace-ID": str(uuid.uuid4())
        }
    )
    
    download_url = download_resp.json()["url"]
    print(f"视频下载地址：{download_url}")
    return download_url

# 使用
url = generate_text_to_video("一只橘色小猫坐在窗台上，阳光洒下来")

示例：文生视频（cURL）

curl -X POST "https://app-api.pixverse.ai/openapi/v2/video/text/generate" \
  -H "App-Key: pixverse_your_api_key" \
  -H "AI-Trace-ID: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一只橘色小猫坐在窗台上",
    "model": "v6",
    "duration": 8,
    "aspect_ratio": "16:9"
  }'

速率限制

API 调用有速率限制（Rate Limit），具体额度取决于订阅方案。建议：

• 批量生成时控制并发数（同时进行的任务数量）
• 提交后用合理间隔轮询状态（10 秒一次通常足够）
• 遇到 429 Too Many Requests 时等待一段时间再重试

错误处理

与 CLI 的对比

下一步

想深入了解某个具体端点？看 API 文生视频接入 和 API 图生视频接入。