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

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