AvatarTalk for agents
For agents generating a video from text or speech, we recommend the AvatarTalk Lightning API. Get a price in satoshis, pay one Bitcoin Lightning invoice with your wallet, and download the MP4. The public video endpoints require no account or API key.
Request a quote
Choose one input per video. Run the examples in one Bash session with curl and jq. Keep the quote and its invoice with the job so you can resume after a restart.
For text, send the words the avatar should speak.
API=https://api.avatartalk.ai
QUOTE=$(curl -fsS "$API/lightning/request-video/text" \
-H 'Content-Type: application/json' \
-d '{"text":"Your order is ready for pickup."}')
For a recording, use the audio endpoint instead. Upload a mono, 16 kHz, 16-bit PCM WAV as the multipart field audio.
API=https://api.avatartalk.ai
QUOTE=$(curl -fsS "$API/lightning/request-video/audio" \
-F 'audio=@speech.wav;type=audio/wav')
Both endpoints return duration in seconds, amount in satoshis and a bolt11_invoice.
Pay the invoice
INVOICE=$(jq -er '.bolt11_invoice' <<< "$QUOTE")
jq '{amount, duration, bolt11_invoice}' <<< "$QUOTE"
Pass that exact BOLT11 invoice to the paying wallet. Before authorizing payment, match the decoded amount to the quote, check expiry and apply the user's spending limit including routing fees. If the agent has no wallet or spending permission, present the invoice and quoted price to the user. Keep wallet credentials and recovery words private.
Check settlement
curl -fsS "$API/lightning/payment/$INVOICE" | jq '{status, amount_sat}'
Proceed when status is paid. While it is pending, poll the same URL with backoff and a deadline. If the wallet reports success but the deadline passes, keep the receipt and resume checking this invoice later. On this endpoint, compare prices using amount_sat; the separate amount field is in USD.
If the deployed OpenAPI schema lists payment_preimage on GenerateVideoRequest, a settled wallet payment can also be redeemed while the API still shows pending. Add the 64-character hexadecimal preimage from the wallet receipt to the generation request. Treat the invoice and proof as private job data.
Download the MP4
Use the original invoice and choose an avatar. This example requests English speech with a neutral expression. The default avatar is european_woman. Each paid request covers one generation and one download.
jq -n --arg invoice "$INVOICE" \
'{bolt11_invoice:$invoice, avatar:"european_woman", emotion:"neutral", language:"en"}' |
curl -fsS "$API/lightning/generate-video" \
-H 'Content-Type: application/json' --data-binary @- \
-o avatar.mp4.part && mv avatar.mp4.part avatar.mp4
The successful response body is binary video/mp4. Save it as it arrives. An interrupted download cannot be resumed. Serialize generation attempts for each invoice.
Recover a job
- 400 — Read the JSON
detail. For an unpaid invoice, return to the status endpoint. For an invalid proof, check the wallet receipt. If the invoice has already been used, look for the saved video. - 404 — Check that the stored invoice is complete and came from the same API host.
- 409 or interrupted download — Generation may still be running or the invoice may already be redeemed. Check the active job and saved file before retrying with the same invoice. A paid status alone does not tell you whether a file was delivered.
- 422 — Correct the request fields from the validation response.
- 503 — The payment service is unavailable. Back off. If a payment was attempted, reconcile it with the wallet before requesting another invoice.
If a paid request is marked used and you have no complete file, contact AvatarTalk support with the request time and error detail. Remove invoices, payment proofs and wallet credentials from logs you share.
Other integrations
- Live API schema — Inspect the routes and request fields available on the deployed API.
- API reference and examples — Look up avatar IDs, languages and example payloads.
- Avatar API and playground — For an existing credits account, use a bearer API key with
POST /inferenceto receive video URLs. Download the generated file from the returnedmp4_url. - LiveKit Agents integration — Give a real-time voice agent an avatar during a conversation.