Polling

Polling is a supported alternative to webhooks. You do not need a public callback endpoint or a webhook signing secret—only your API key

Submit Without A Webhook

Use the quickstart environment variables, then submit video and audio with an idempotency key. Omit webhook_url. Save the id from the 202 Accepted response

curl -X POST "$LIPS_API/v1/renders" \
  -H "Authorization: Bearer $LIPS_KEY" \
  -H "Idempotency-Key: render-001" \
  -H "Content-Type: application/json" \
  -d '{"video":{"url":"https://example.com/video.mp4"},"audio":{"url":"https://example.com/audio.wav"},"engines":["musetalk"],"sync_mode":"loop"}'

Poll The Render ID

curl --fail-with-body "$LIPS_API/v1/renders/<render-id>" -H "Authorization: Bearer $LIPS_KEY"

Repeat this authenticated GET about every five seconds from your backend. Read status, stage and progress_percent. Stop polling at completed, failed or cancelled, and inspect every entry in engines: completed engines may have usable outputs even if another engine failed

Overall progress is stage-weighted; engine progress includes frames_done and frames_total. The billing object reports accrued and debited demo credit in microUSD. Failed jobs preserve the last percentage; INSUFFICIENT_FUNDS means unfinished work was stopped. The current owner-only demo disables GPU rendering and reports GPU_EXECUTION_DEFERRED after CPU validation

Download The Results

Completed engines expose output.url. Download that URL directly. Each GET creates fresh signed URLs valid for 15 minutes; fetch the render again if a URL expires

curl --fail '<completed engine output.url>' -o completed.mp4

Polling Limits And Recovery

Each poll counts toward the default 60 requests per minute, shared with your other API calls. Five-second polling uses about 12 requests per minute per render. On 429, wait for Retry-After (currently 60 seconds); retry temporary 503 responses with backoff. Stop and fix authentication on 401; treat 404 or 410 as unavailable or expired records

Set a deadline suitable for your application. Stopping your polling loop does not cancel rendering. Use POST /v1/renders/{id}/cancel to request cancellation. You can also resume polling a saved ID later or combine polling with webhooks