RonanCodes/pixverse

pixverse — text/image → AI video

PixVerse Platform API: submit a generation, poll for the result, get an MP4 URL. Async (no streaming). Docs: https://docs.platform.pixverse.ai

Auth + base

• Base URL: https://app-api.pixverse.ai
• API key from the PixVerse platform → store as PIXVERSE_API_KEY (a Worker secret / .dev.vars locally; NEVER commit it).
• Every request needs three headers:
  • API-KEY: <key>
  • Ai-trace-id: <a fresh UUID per request> — load-bearing: reuse the same trace-id and you get the SAME video back, not a new one. Generate a new UUID per submit.
  • Content-Type: application/json

1. Submit a generation

Text-to-video — POST /openapi/v2/video/text/generate

{
  "prompt": "string, <= 5000 chars",
  "model": "v5",
  "duration": 5,
  "quality": "540p",
  "aspect_ratio": "16:9",
  "motion_mode": "normal",
  "negative_prompt": "",
  "seed": 0,
  "water_mark": false
}

Required: prompt, model, duration, quality, aspect_ratio.

• model: v3.5, v4, v4.5, v5, v5.5, v5.6, v6, c1. Safe default v5.
• duration: 5 or 8 (v3.5–v5.6); 1–15 (v6/c1).
• quality: 360p / 540p / 720p / 1080p.
• aspect_ratio: 16:9, 9:16, 1:1, 4:3, 3:4, ... (more on v6/c1).
• Audio/lipsync: generate_audio_switch (v5.5+), sound_effect_switch + sound_effect_content (v5 and below), lip_sync_tts_*.

Image-to-video — POST /openapi/v2/video/img/generate (same auth + polling; the body takes an uploaded image reference plus prompt/model/duration/quality — see docs image-to-video-generation).

Submit response:

{ "ErrCode": 0, "ErrMsg": "success", "Resp": { "video_id": 123456 } }

ErrCode === 0 is success; otherwise throw with ErrMsg. Keep Resp.video_id.

2. Poll for the result

GET /openapi/v2/video/result/{video_id} (same three headers).

{ "ErrCode": 0, "Resp": { "status": 1, "url": "https://.../out.mp4", "prompt": "...", "seed": 0 } }

• status === 1 → done, Resp.url is the MP4.
• Other statuses → still generating or failed. Poll every ~10s, time out after ~8 min, and treat a known-failure/terminal non-1 status as an error (print the status; don't spin forever).

Reference script

A Node/tsx script (global fetch, crypto.randomUUID(), no deps):

1. Read PIXVERSE_API_KEY from env. Build a prompt.
2. POST text/generate with a fresh Ai-trace-id; read Resp.video_id.
3. Loop: GET result/{video_id} until status === 1; return Resp.url.
4. Save { prompt, video_id, url } somewhere; print the URL.

# load the key, then run
set -a; source .dev.vars; set +a
pnpm tsx scripts/pixverse-video.ts --prompt "a top-down cooking video of ..."

curl smoke test:

curl -s https://app-api.pixverse.ai/openapi/v2/video/text/generate \
  -H "API-KEY: $PIXVERSE_API_KEY" -H "Ai-trace-id: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{"prompt":"a cinematic top-down shot of pasta boiling","model":"v5","duration":5,"quality":"540p","aspect_ratio":"16:9"}'
# -> {"ErrCode":0,"Resp":{"video_id":N}}, then:
curl -s https://app-api.pixverse.ai/openapi/v2/video/result/N \
  -H "API-KEY: $PIXVERSE_API_KEY" -H "Ai-trace-id: $(uuidgen)"

Gotchas

• New Ai-trace-id per request or you get a cached/duplicate video.
• Generation is async + slow (tens of seconds to minutes). For a live demo, pre-generate and cache the MP4 URL; do not block a user request on a generate+poll loop.
• The result url is a download link; persist the MP4 (R2 / your storage) if you need it long-term, don't assume the URL is permanent.
• Costs credits per generation. Keep quality/duration modest while iterating.
• Keep the key server-side only (Worker secret); never ship it to the browser.

Credits: the API is NOT your web subscription

The PixVerse Platform API (platform.pixverse.ai) is billed SEPARATELY from the PixVerse web app (app.pixverse.ai). API credits and web credits do not cross over. A web subscription does NOT fund the API, so the API returns ErrCode 500090: Insufficient balance even with a full web plan. The API entry tier is ~$100/mo (Essential, ~15k credits); the web app is cheap pay-as-you-go. For one-off / hackathon generation, use the WEB app (paste prompt + settings), not the API. Reach for the API only when you have an API plan and need programmatic/batch generation.

Recipe / food video playbook (learned in smart-cart, 2026-06-21)

Two clips per dish, different jobs:

A. Living photo (the card hero): 1:1, image-to-video, ~5s

The recipe photo subtly comes alive. Settings: upload the recipe photo as the start frame, model V6, 720p, 1:1, 5s, Multi-Shot OFF, motion strength LOW, Audio OFF. Hard-won rules:

• Multi-Shot OFF. Multi-shot generates multiple shots, so it CUTS to a different frame. Off = one continuous take.
• Motion strength is the real subtlety lever, not the prompt. Image-to-video over-animates by default; turn the motion intensity to minimum.
• Add NOTHING. Telling it to add "steam" renders black smudges; "a spoon dips in" grafts a spoon onto an existing object (it stuck one on the lemon). Prompt: "keep every object identical, add nothing: no steam, no utensils, no hands, no new food."
• No "warm light drifting" — it invents a moving sun/glow. Use "even, consistent light, no glow, no sun."
• No flowing liquids (sauce pouring) — looks wrong when reversed for the loop.
• Loop via boomerang at HOSTING, not the prompt. A one-directional clip never lands back at the start, so the loop jumps. Fix with ffmpeg forward+reverse so a plain <video loop> is seamless:

  ffmpeg -y -i in.mp4 -filter_complex "[0:v]reverse[r];[0:v][r]concat=n=2:v=1:a=0,format=yuv420p[v]" -map "[v]" -an boomerang.mp4
  

  This frees the prompt to use a gentle slow push-in (forward = in, reverse = out, back to start).
• In-app: autoplay it — <video autoPlay loop muted playsInline poster={photo}>, pointer-events-none so it never steals the card tap. Muted+playsInline+autoplay is the only combo iOS autoplays. poster = the photo so frame 0 matches (no flash).

B. Full how-to (View recipe video): 16:9, ~12s, text-to-video

The classic step montage. Settings: NO start image (a start image opens on the finished dish; a how-to must start on raw ingredients), text-to-video, V6, 720p, 16:9, 12s, Multi-Shot ON, Audio ON. Optionally set the recipe photo as the last frame via the Transition feature so it lands on the real dish.

Grounding + tasty

• Ground every prompt in the real recipe (ingredients + steps + the plated photo's actual look). A bare "risotto" prompt invents a generic creamy-white dish that looks nothing like the real one. Read the recipe image first.
• Crave-able dishes glisten better (saucy / cheesy / glazed) than a healthy bowl. Pick those to show the look off.
• Aspect: 1:1 framed cooking best for cards/feed (16:9 and 9:16 both came out too zoomed/cropped for the hero); 16:9 for the how-to.
• Always end prompts with "no text overlays" (stops garbled baked-in captions).

Hosting (smart-cart pattern)

Generate (web app) → boomerang (ffmpeg) → upload to an R2 public bucket → store the public URL on the recipe row (recipe_media.video_url) → the card autoplays it. Pre-generate + cache; never generate on the request path. POC CLI: scripts/pixverse-cooking-video.ts (needs an API plan to run).