PixVerse 中文文档 下载 App

PixVerse API 文生视频接入 — complete guide

端点概览

文生视频的 API 端点是：

POST https://app-api.pixverse.ai/openapi/v2/video/text/generate

这是 PixVerse API Platform 最常用的端点——输入文字提示词，返回一个 video_id，然后轮询状态直到完成。

请求头

App-Key: pixverse_your_api_key_here
AI-Trace-ID: uuid-string-for-tracking
Content-Type: application/json

请求体参数

{
  "prompt": "一只橘色小猫坐在温暖的窗台上，阳光洒下来",
  "model": "v6",
  "duration": 8,
  "aspect_ratio": "16:9",
  "resolution": "1080p",
  "voice": false,
  "template_id": null
}
参数类型必填说明
promptstring✅提示词文本
modelstring❌模型版本：v6 / v5 / v5.6（默认最新）
durationint❌时长（秒）：5 / 8 / 10 / 15
aspect_ratiostring❌"16:9" / "9:16" / "1:1"
resolutionstring❌"720p" / "1080p"
voicebool❌是否开启原生音频（默认 false）
template_idstring❌使用的模板 ID

响应示例

成功提交（HTTP 200）

{
  "success": true,
  "video_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": 5,
  "estimated_time": 60
}

参数错误（HTTP 400）

{
  "success": false,
  "error_code": 1001,
  "error_message": "prompt cannot be empty"
}

Python 完整示例

import requests
import uuid
import time
import os

class PixVerseAPI:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://app-api.pixverse.ai"
        self.headers = {"App-Key": api_key}
    
    def _trace_id(self):
        return str(uuid.uuid4())
    
    def text_to_video(self, prompt, model="v6", duration=8,
                      aspect_ratio="16:9", resolution="1080p",
                      voice=False, timeout=300):
        """完整的文生视频流程：提交 → 轮询 → 下载"""
        
        # Step 1: 提交
        submit = requests.post(
            f"{self.base_url}/openapi/v2/video/text/generate",
            headers={**self.headers, "AI-Trace-ID": self._trace_id()},
            json={
                "prompt": prompt,
                "model": model,
                "duration": duration,
                "aspect_ratio": aspect_ratio,
                "resolution": resolution,
                "voice": voice
            }
        )
        submit.raise_for_status()
        video_id = submit.json()["video_id"]
        
        # Step 2: 轮询状态
        start = time.time()
        while time.time() - start < timeout:
            status = requests.get(
                f"{self.base_url}/openapi/v2/video/status/{video_id}",
                headers={**self.headers, "AI-Trace-ID": self._trace_id()}
            ).json()
            
            state = status["status"]
            if state == 1:  # SUCCESS
                break
            elif state in (2, 3):  # FAILED / TIMEOUT
                raise Exception(f"生成失败：{status}")
            
            time.sleep(10)
        else:
            raise Exception("生成超时")
        
        # Step 3: 获取下载地址
        download = requests.get(
            f"{self.base_url}/openapi/v2/video/download/{video_id}",
            headers={**self.headers, "AI-Trace-ID": self._trace_id()}
        ).json()
        
        return download["url"]
    
    def download_video(self, url, save_path):
        """下载视频到本地"""
        os.makedirs(os.path.dirname(save_path) or ".", exist_ok=True)
        with requests.get(url, stream=True) as r:
            r.raise_for_status()
            with open(save_path, "wb") as f:
                for chunk in r.iter_content(chunk_size=8192):
                    f.write(chunk)

# 使用示例
api = PixVerseAPI("pixverse_your_api_key")
video_url = api.text_to_video(
    prompt="一只橘色小猫坐在窗台上，阳光洒下来，轻微推进",
    model="v6",
    duration=8,
    aspect_ratio="16:9",
    resolution="1080p"
)
api.download_video(video_url, "./output/cat.mp4")

cURL 快速测试

# 1. 提交任务
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",
    "resolution": "1080p"
  }'

# 2. 轮询状态（把 video_id 替换成上一步返回的值）
curl "https://app-api.pixverse.ai/openapi/v2/video/status/YOUR_VIDEO_ID" \
  -H "App-Key: pixverse_your_api_key" \
  -H "AI-Trace-ID: $(uuidgen)"

# 3. 获取下载地址
curl "https://app-api.pixverse.ai/openapi/v2/video/download/YOUR_VIDEO_ID" \
  -H "App-Key: pixverse_your_api_key" \
  -H "AI-Trace-ID: $(uuidgen)"

状态码参考

status含义处理
1成功调下载端点
2失败检查 error_message，可能是提示词问题
3超时考虑重试或联系支持
4处理中继续轮询
5排队中继续轮询

批量生产最佳实践

并发控制

同时提交多个任务时，控制并发数在 API 限制内：

import asyncio
import aiohttp

async def batch_generate(prompts, concurrency=5):
    sem = asyncio.Semaphore(concurrency)
    
    async def one(prompt):
        async with sem:
            return await generate_one(prompt)
    
    tasks = [one(p) for p in prompts]
    return await asyncio.gather(*tasks)

重试策略

def safe_generate(prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            return api.text_to_video(prompt)
        except Exception as e:
            if "RATE_LIMITED" in str(e):
                time.sleep(60 * (attempt + 1))  # 递增等待
            elif attempt == max_retries - 1:
                raise
    return None

断点续跑

把生成结果存到数据库或 JSON 文件，批量任务中断后可以跳过已完成的：

completed = load_json("results.json")
prompts = load_json("prompts.json")

for prompt in prompts:
    if prompt["id"] in completed:
        continue
    try:
        url = api.text_to_video(prompt["text"])
        completed[prompt["id"]] = url
        save_json("results.json", completed)
    except Exception as e:
        print(f"失败：{prompt['id']} - {e}")

与 Web 界面的配合

API 返回的 video_id 可以在 Web 界面中查看——打开 PixVerse 控制台，你会看到通过 API 提交的任务，和手动生成的并排显示。

错误排查清单