PixVerse API 图生视频接入 — image-to-video complete guide

端点概览

图生视频的 API 端点是：

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

与文生视频的区别是多了一个输入图片。PixVerse API 支持两种图片输入方式，选择适合你场景的即可。

图片上传方式

方式一：Base64 编码（推荐小图）

把图片文件转成 Base64 字符串，直接放进 JSON 请求体。适合小图（<10MB）。

import base64

with open("photo.jpg", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode()

方式二：URL 引用（推荐大图）

先把图片上传到你自己的 CDN 或对象存储（AWS S3、Cloudflare R2、阿里云 OSS 等），然后把公开访问的 URL 放进请求体。适合大图或不想处理 Base64 编码。

image_url = "https://your-cdn.example.com/assets/photo.jpg"

选择建议

请求体参数

{
  "prompt": "让图片动起来，镜头缓慢推进",
  "image": "base64_string_or_url",
  "image_type": "base64",
  "model": "v6",
  "duration": 8,
  "aspect_ratio": "16:9",
  "resolution": "1080p"
}

请求头

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

Python 完整示例

Base64 方式

import requests
import uuid
import time
import base64

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

def image_to_video(image_path, prompt, model="v6"):
    # 读取图片并转为 Base64
    with open(image_path, "rb") as f:
        image_b64 = base64.b64encode(f.read()).decode()
    
    # 提交
    resp = requests.post(
        f"{BASE_URL}/openapi/v2/video/image/generate",
        headers={
            "App-Key": API_KEY,
            "AI-Trace-ID": str(uuid.uuid4()),
            "Content-Type": "application/json"
        },
        json={
            "prompt": prompt,
            "image": image_b64,
            "image_type": "base64",
            "model": model,
            "duration": 8,
            "aspect_ratio": "16:9",
            "resolution": "1080p"
        }
    )
    resp.raise_for_status()
    video_id = resp.json()["video_id"]
    
    # 轮询（和文生视频相同逻辑）
    while True:
        status = requests.get(
            f"{BASE_URL}/openapi/v2/video/status/{video_id}",
            headers={
                "App-Key": API_KEY,
                "AI-Trace-ID": str(uuid.uuid4())
            }
        ).json()
        
        state = status["status"]
        if state == 1:
            break
        elif state in (2, 3):
            raise Exception(f"失败：{status}")
        
        time.sleep(10)
    
    # 获取下载地址
    download = requests.get(
        f"{BASE_URL}/openapi/v2/video/download/{video_id}",
        headers={
            "App-Key": API_KEY,
            "AI-Trace-ID": str(uuid.uuid4())
        }
    ).json()
    
    return download["url"]

# 使用
url = image_to_video(
    image_path="./product-photo.jpg",
    prompt="让产品从静态变成动态，镜头缓慢推进，保持产品外观和背景不变"
)

URL 方式

def image_to_video_url(image_url, prompt, model="v6"):
    resp = requests.post(
        f"{BASE_URL}/openapi/v2/video/image/generate",
        headers={
            "App-Key": API_KEY,
            "AI-Trace-ID": str(uuid.uuid4()),
            "Content-Type": "application/json"
        },
        json={
            "prompt": prompt,
            "image": image_url,
            "image_type": "url",
            "model": model,
            "duration": 8
        }
    )
    # 后续轮询和下载逻辑相同...

cURL 快速测试（Base64 方式）

# 把图片转成 Base64
IMAGE_B64=$(base64 -i photo.jpg)

# 提交任务
curl -X POST "https://app-api.pixverse.ai/openapi/v2/video/image/generate" \
  -H "App-Key: pixverse_your_api_key" \
  -H "AI-Trace-ID: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{
    \"prompt\": \"让图片动起来，轻微推进\",
    \"image\": \"$IMAGE_B64\",
    \"image_type\": \"base64\",
    \"model\": \"v6\",
    \"duration\": 8,
    \"aspect_ratio\": \"16:9\"
  }"

文生 vs 图生 API 对比

输入图片建议

✅ 好的输入图片

• 分辨率：1024px 以上（更高更好）
• 格式：JPG / PNG 优先
• 主体清晰、边缘明确
• 构图有力、歧义少
• 无水印、无文字叠加

❌ 不好的输入图片

• 主体模糊、被遮挡
• 背景杂乱
• 低分辨率
• 包含复杂文字或 Logo

常见问题

Q: 图生视频的 prompt 应该怎么写

和文生视频不同，图生视频的 prompt 重点是运动描述：

• ✅ 好的：「产品从静态变成动态，镜头缓慢推进到特写，光线保持和原图一致」
• ❌ 不好的：「一个很棒的产品视频」（没有描述运动）

提示词中明确说明「保持主体和外观与原图一致」会更好。

Q: 图片上传失败怎么办

• Base64 太大：检查图片大小，API 可能有上限
• URL 不可达：确保 URL 是公网可访问的（不要用内网地址）
• 图片格式不对：用常见格式（JPG、PNG）

Q: 能同时传入参考图和主体参考吗

部分版本可能支持多个图片参数（image + reference_image），具体以最新 API 文档为准。如果需要角色锁定，建议先用一张干净的参考图做主图，在 prompt 里描述需要的一致性。

和 CLI 的对应关系

API 图生视频对应的 CLI 命令：

pixverse create video \
  --prompt "让图片动起来，轻微推进" \
  --image ./photo.jpg \
  --model v6

CLI 自动帮你处理图片读取和上传，适合本地开发和脚本场景。