PixVerse API: Platform, Endpoints and Credits

PixVerse publishes an official REST API, and it is not the consumer product. Requests go to https://app-api.pixverse.ai, every call carries two headers, generation is asynchronous, and credits are metered per second.

Three names, and a second credit balance

Keep three surfaces apart. PixVerse is the consumer site. PixVerse Platform is the API product, with its console at platform.pixverse.ai and documentation at docs.platform.pixverse.ai. app-api.pixverse.ai is the request domain, and the PixVerse topic hub covers the models.

The subscription page opens with two warnings: API memberships are separate from the PixVerse Web membership, and API credits cannot be used with PixVerse Web. A web plan does not raise an API ceiling, and plan changes are not supported yet.

The access path that is not in this API

PixVerse R1, the real-time world model, is not a model-selector value. Its API access is a partner programme: 720p output, integrated audio, up to 300 seconds of continuous generation, entered by application. V6 and C1 are the self-service models.

Authentication needs two headers

The two required headers

API-KEY carries the console key, shown once. Ai-trace-id must be a UUID unique to each request. Recycling one is documented with no hedging: use the same Ai-trace-id twice and you will not get a new video — the documented first cause of a task that hangs in generating.

Where the key comes from

Create an app key in the console; a PixVerse consumer account logs in directly. The console renders on the client, so the docs are the only readable record. A Recraft key needs one Bearer header, which is why the second PixVerse header catches people out.

Your first request, from submit to download

Three steps cover the lifecycle: submit a task, keep the video_id, poll it, then download from url. The web walkthrough does the same job in the console.

# Requires curl and jq. Generate a fresh Ai-trace-id for every request.
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}}

# Poll until the status moves from 5 to 1, then read `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'

The wrapper is ErrCode, ErrMsg and Resp. quality, duration and generate_audio_switch decide the bill; audio defaults to false, and aspect_ratio is text-to-video and Fusion only.

Image-to-video: upload for an img_id

Image-to-video is two calls. Upload the still and the response returns an img_id; the generation call sends that id, not a URL. Accepted formats are png, webp, jpeg and jpg, up to 10000 pixels, with at least 1024×1024 recommended.

# Step 1: upload the still and capture the 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":"..."}}

# Step 2: send that img_id, with the same two headers.
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
  }'

A file path in place of an img_id produces 400032; an oversized image produces 500030.

The endpoint surface, statuses and error codes

Generation lives under https://app-api.pixverse.ai/openapi/v2/, and the model parameter picks v6 or c1.

Video extension is the one hard capability gap: V6 only; every other capability is standalone, with its own endpoint, requirements and pricing.

C1 owns the storyboard route: static panel layouts become a continuous sequence, so the sheet above is the input shape the model reads.

Result statuses

Status is a number in the body, not an HTTP code: 5 waiting, 1 success, 7 moderation failure, 8 generation failure. url resolves only at status 1, and filtered videos are refunded automatically, so status 7 costs nothing.

Error codes that change your client code

500090 is insufficient balance. 500071 means the chosen effect rejects 720p or 1080p. 400018/400019 cap prompt length at 2048 characters — contradicting the model pages, where V6 and C1 document 5000. Keep the lower one until the vendor reconciles them.

Concurrency, not requests per minute

The rate-limit page publishes no request-per-minute figure, only simultaneous generating tasks: Concurrent Requests.

Exceeding it returns 500044, reached the limit for concurrent generations; the documented remedy is an upgrade or an email to api@pixverse.ai.

# A submit helper that treats 500044 as backpressure, not as a hard failure.
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'
}

Credits are billed per second of output

Generation is priced per second, not per request, and the rate depends on resolution and audio.

C1 costs one credit more per second at every tier. A Fusion call carrying video_references doubles the rate, so V6 at 1080p without audio moves from 18 to 36. The pricing page publishes one currency anchor: $1 = 5 videos (v6, 720p, 5s, no audio, with Starter pack). Dollar prices and monthly totals are not published. For another vendor’s video models, our Seedance notes are the counterpart.

API output rights are not the web terms

Two terms of service cover the same brand, run by two entities, and disagree on commercial output.

“PixVerse output is non-commercial only” is therefore not a safe summary. What the API terms forbid is reselling the interface: selling invocation services, integrating the API into third-party apps for resale, or building a mirror service.

Frequently asked questions

Can web credits be used with the API? No. API memberships are separate from the web membership, and API credits cannot be used with PixVerse Web.

Why is my task stuck in generating? Almost always a reused Ai-trace-id; every generation needs a fresh UUID.

What happens when credits run out? The API returns 500090. Per-plan totals and dollar prices are not published.

Are credits refunded when moderation filters a video? Yes. Status 7 is a moderation failure, and those credits are refunded.

Is there a request-per-minute limit published? No. The limit is concurrent generating tasks, 3 on Free through 25 on Business; over it returns 500044.

Create the key on the API platform and treat 500044 as backpressure.

Published

Sep 14, 2026

Information verified

Sep 14, 2026

By

AI Tool Blog Editorial Team