TalkPix Python client

Official Python client for the TalkPix API. Send one portrait photo plus a script (or an audio file) and get back a lip-synced talking video as an MP4.

• Zero dependencies, Python 3.8+ (standard library only)
• Webhook signature verification built in
• Same API as the Node.js client

Full API reference: talkpix.ai/developers

Install

pip install talkpix

Quick start

Create an API key in your account at talkpix.ai/account/api and keep it on your server.

from talkpix import TalkPix

talkpix = TalkPix()  # reads TALKPIX_API_KEY

video = talkpix.videos.create(
    image_url="https://example.com/portrait.jpg",
    script="Hi! This video was made with one API call.",
    voice="zephyr",
    language="en-US",
)

done = talkpix.videos.wait_for_completion(video["id"])
print(done["status"], done.get("video_url"))

Check the cost first

estimate is free and tells you how many credits a script will reserve before anything renders:

estimate = talkpix.estimate(script="Happy birthday, Sam!", resolution="720p")
# {"estimated_seconds": ..., "credits": ..., "max_seconds": ..., "words": ...}

account = talkpix.me()
print(account["credits"]["balance"])

Credits are reserved when a render starts and reconciled to the rendered length when it finishes. A failed render returns its credits automatically.

Use your own audio

video = talkpix.videos.create(
    image_url="https://example.com/portrait.jpg",
    audio_url="https://example.com/message.mp3",
)

Upload local files

with open("portrait.jpg", "rb") as f:
    photo = talkpix.upload_file(f.read(), content_type="image/jpeg")

video = talkpix.videos.create(
    image_key=photo["key"],
    script="This photo was uploaded straight from my server.",
    voice="zephyr",
    language="en-US",
)

Voices and languages

info = talkpix.voices()
print(info["voices"], info["languages"])

Webhooks

Pass webhook_url to get a signed video.completed or video.failed event instead of polling. Verify it against the raw body:

from talkpix import verify_webhook_signature

@app.post("/hooks/talkpix")  # Flask
def talkpix_hook():
    ok = verify_webhook_signature(
        os.environ["TALKPIX_WEBHOOK_SECRET"],
        request.headers.get("TalkPix-Signature"),
        request.get_data(),
    )
    if not ok:
        return "", 400
    event = request.get_json()
    # event["type"] == "video.completed" -> event["data"]["video_url"]
    return "", 200

List renders

page = talkpix.videos.list(limit=20, status="completed")
if page["has_more"]:
    nxt = talkpix.videos.list(starting_after=page["next_starting_after"])

Errors

Every API error is raised as TalkPixError with status, type and, for validation errors, the param that failed:

from talkpix import TalkPixError

try:
    talkpix.videos.create(image_url="https://example.com/portrait.jpg")
except TalkPixError as error:
    print(error.status, error.type, error.param, error.message)

If a render is refused because the balance can't cover it, add credits at talkpix.ai/pricing.

Pricing

API renders use the same credit wallet and rates as the web app. Credits come in one-time packs from $5, never expire, and no subscription is required.

License

MIT