Metadata-Version: 2.1
Name: talkpix
Version: 0.1.0
Summary: Official Python client for the TalkPix API: turn a photo and a script or audio into a lip-synced talking video.
Author-email: TalkPix <support@talkpix.ai>
License: MIT
Project-URL: Homepage, https://www.talkpix.ai
Project-URL: Documentation, https://www.talkpix.ai/developers
Project-URL: Source, https://github.com/TalkPix-AI/talkpix-api-examples
Project-URL: Node.js client, https://www.npmjs.com/package/talkpix
Keywords: talkpix,talking photo,lip sync,ai video,avatar,text to video,api
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Multimedia :: Video
Classifier: Intended Audience :: Developers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE

# TalkPix Python client

Official Python client for the [TalkPix](https://www.talkpix.ai) 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](https://www.npmjs.com/package/talkpix)

Full API reference: [talkpix.ai/developers](https://www.talkpix.ai/developers)

## Install

```bash
pip install talkpix
```

## Quick start

Create an API key in your account at [talkpix.ai/account/api](https://www.talkpix.ai/account/api) and keep it on your server.

```python
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:

```python
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

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

## Upload local files

```python
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

```python
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:

```python
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

```python
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:

```python
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](https://www.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
