Percify API async jobs: statuses, polling and timeouts

Every Percify API job is asynchronous: the call that starts it returns an id at once, and the file arrives later. Read the result by polling with ?wait=45, which holds the request on Percify’s side until the job ends, or by passing a webhook URL so Percify posts the result to you. Failed and timed-out jobs refund their credits automatically.

Generation statuses

These apply to POST /v1/run and GET /v1/generations/{id}.

Status	Meaning	Final
`processing`	The model is working. New runs start here.	No
`succeeded`	Done. Files are in `output.urls`.	Yes
`failed`	Stopped. The reason is in `error` and the credits were refunded.	Yes

The OpenAPI document also lists queued. Treat it like processing if you ever see it.

Three ways to wait

Long-poll (recommended)
Short poll
Webhook

Call GET /v1/generations/{id}?wait=45 in a loop. Each call returns as soon as the job ends, or after 45 seconds with stillRunning: true. wait accepts 5 to 55.

curl -s "https://api.percify.io/v3/playground/v1/generations/$GEN_ID?wait=45" \
  -H "Authorization: Bearer $PERCIFY_API_TOKEN"

Call GET /v1/generations/{id} without wait every few seconds. Keep each key under 60 requests a minute across all your jobs.

Pass "webhook": "https://your-server.example/percify" in the run body. Percify sends one POST when the job succeeds or fails. See Webhooks.

You do not have to poll for a job to finish. Percify also checks running jobs in the background, so outputs are saved and webhooks are sent either way.

How long can a job run?

A generation that has not finished fails with Generation timed out after 15 minutes plus 5 seconds for every second of input audio or video. Any generation still processing after 30 minutes is failed as well. In both cases the credits are refunded. Lip-sync and other video models take the longest, so use wait or a webhook for them rather than a tight loop.

What happens to credits?

Moment	Credits
The run is rejected before it starts (bad input, moderation, balance, limits)	Never charged
The run starts	Charged, shown in `creditsSpent`
The model cannot start the job	Refunded in the same request
The job fails or times out	Refunded automatically
You retry with the same `Idempotency-Key`	Not charged again

Retry safely

Network errors and timeouts on your side do not tell you whether a run started. Send an Idempotency-Key header on POST /v1/run, and reuse the same value when you retry. Percify returns the generation it already created and does not charge twice.

curl -s -X POST https://api.percify.io/v3/playground/v1/run \
  -H "Authorization: Bearer $PERCIFY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-voiceover" \
  -d '{"modelId":"zonos2","input":{"text":"Your order is on its way.","audio":"https://example.com/voice-sample.wav"}}'

Longer pipelines

The replication and short-video endpoints run several generations for you and have their own statuses.

Job	Poll	Statuses	Final
Video analysis	`GET /v3/replicate/v1/analyses/{id}`	`analyzing`	`ready`, `failed`
Replication run	`GET /v3/replicate/v1/runs/{id}`	`generating`, `stitching`	`done`, `failed`
Short video	`GET /v3/mascot/api/{jobId}`	`scripting`, `portrait`, `animating`, `captioning`	`done`, `failed`

These endpoints have no wait parameter, so poll them every few seconds or pass a webhook. Details are on Analyze and replicate a short video and Make a short video from a topic.

Get a generation

The polling endpoint and its fields.

Webhooks

Payloads and signature headers.

Errors and rate limits

What each failure means.

Code examples

A full run-and-wait loop in three languages.

Get started

Generations

Async and webhooks

Build with the API

Account

MCP

Percify API async jobs: statuses, polling and timeouts

Generation statuses

Three ways to wait

How long can a job run?

What happens to credits?

Retry safely

Longer pipelines

Get a generation

Webhooks

Errors and rate limits

Code examples

​Generation statuses

​Three ways to wait

​How long can a job run?

​What happens to credits?

​Retry safely

​Longer pipelines

​Related

Get a generation

Webhooks

Errors and rate limits

Code examples

Generation statuses

Three ways to wait

How long can a job run?

What happens to credits?

Retry safely

Longer pipelines

Related