cutpro 0.1.0__tar.gz

cutpro-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - run: uv run --python ${{ matrix.python }} --group dev mypy
+      - run: uv run --python ${{ matrix.python }} --group dev pytest -q
+      - run: uv build

cutpro-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*.*.*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - name: Tag matches pyproject.toml
+        run: test "v$(grep -m1 '^version = ' pyproject.toml | cut -d'"' -f2)" = "$GITHUB_REF_NAME"
+      - run: uv run --group dev mypy
+      - run: uv run --group dev pytest -q
+      - run: uv build
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
+        with:
+          # A project token in the `pypi` environment; trusted publishing replaces it once it is configured on PyPI.
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          attestations: false
+
+  release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+      - name: GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1 || gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --generate-notes

cutpro-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+uv.lock

cutpro-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cut.Pro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cutpro-0.1.0/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.5
+Name: cutpro
+Version: 0.1.0
+Summary: Cut.Pro API client for Python: Seedance, Wan, Kling, Veo, Nano Banana, Seedream, GPT Image and Gemini TTS with one key, priced per second, image or 1,000 characters
+Project-URL: Homepage, https://cut.pro/docs/en/generations
+Project-URL: Source, https://github.com/getcutpro/sdk-python
+Project-URL: Issues, https://github.com/getcutpro/sdk-python/issues
+Project-URL: Prices, https://cut.pro/en/models
+Author: Cut.Pro
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,api,cutpro,gemini-tts,gpt-image,image-generation,image-to-video,kling,nano-banana,sdk,seedance,seedance-api,seedream,text-to-speech,text-to-video,veo,video-generation,wan
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Cut.Pro Python SDK: Seedance, Wan, Kling, Veo and Nano Banana API in Python
+
+[![PyPI](https://img.shields.io/pypi/v/cutpro)](https://pypi.org/project/cutpro/) [![license](https://img.shields.io/pypi/l/cutpro)](LICENSE)
+
+One API key for video, image and voice models: Seedance 2.5, Wan 3, Kling O3, Veo 3.1, Gemini Omni Flash, Nano Banana Pro, Seedream 5, Qwen Image, GPT Image, Grok Imagine, MiniMax and Gemini TTS voices. Priced per second of video, per image or per 1,000 characters of voice, in reais and dollars: see the [live price list](https://cut.pro/en/models). Pay with Pix or card; companies get an invoice.
+
+Python 3.9 to 3.13, standard library only (no dependencies), fully typed (`py.typed`), sync and asyncio. A pure wheel, so it installs the same way in any environment:
+
+```bash
+pip install cutpro          # pip, virtualenv, Anaconda and Miniconda environments
+uv add cutpro               # uv
+poetry add cutpro           # Poetry
+pdm add cutpro              # PDM
+pipenv install cutpro       # Pipenv
+```
+
+## Quickstart
+
+Create a key at [cut.pro/studio/me/api-keys](https://cut.pro/studio/me/api-keys) and set `CUTPRO_API_KEY`. Every account starts with free credits.
+
+```python
+from cutpro import CutPro
+
+cutpro = CutPro()  # reads CUTPRO_API_KEY
+
+video = cutpro.generations.generate(
+    model="bytedance/seedance-2.5",
+    prompt="a golden retriever surfing a wave at sunset, cinematic",
+    seconds=5,
+    resolution="720p",
+    aspect_ratio="16:9",
+)
+print(video["output"]["url"], video["credits_charged"], "credits")
+```
+
+`generate()` quotes the request, starts it with the quoted total and waits until it is ready. Each step is also its own call.
+
+## Seedance API in Python, step by step
+
+```python
+import uuid
+
+quote = cutpro.generations.quote(model="bytedance/seedance-2.5", prompt="a dog surfing", seconds=5)
+print(quote["credits"], "credits")  # show the price and wait for a yes
+
+started = cutpro.generations.create(
+    model="bytedance/seedance-2.5",
+    prompt="a dog surfing",
+    seconds=5,
+    credits=quote["credits"],
+    idempotency_key=str(uuid.uuid4()),
+)
+
+done = cutpro.generations.wait(started["id"], timeout=600)
+if done["status"] == "ready":
+    print(done["output"]["url"])
+```
+
+- `create()` without `credits` quotes first and agrees to that total. With `credits`, the price is checked on the server: if it changed, nothing is charged and you get `PRICE_CHANGED` with the new total in `extra["credits"]`.
+- `idempotency_key`: repeating the same request with the same key within 24 hours never charges twice.
+- `webhook_url="https://..."` gets a signed POST when the generation ends, instead of waiting.
+
+## Wan 3 image to video
+
+```python
+clip = cutpro.generations.generate(
+    model="alibaba/wan-3",
+    mode="image",
+    image_urls=["https://your-cdn.com/product.jpg"],
+    prompt="the camera slowly orbits the product, soft studio light",
+    seconds=5,
+    resolution="720p",
+)
+```
+
+Local file? `media = cutpro.media.upload(open("product.jpg", "rb").read(), filename="product.jpg", content_type="image/jpeg")` and send `image_ids=[media["id"]]`.
+
+## Nano Banana Pro image with references
+
+```python
+image = cutpro.generations.generate(
+    model="google/nano-banana-pro",
+    mode="references",
+    image_urls=["https://your-cdn.com/person.jpg", "https://your-cdn.com/jacket.jpg"],
+    prompt="the person from the first image wearing the jacket from the second, street photo",
+    aspect_ratio="4:5",
+)
+```
+
+## Gemini TTS voice
+
+```python
+voices = cutpro.models.list(id="google/gemini-3.1-flash-tts")["models"][0]["voices"]
+print([voice["id"] for voice in voices])
+
+voice = cutpro.generations.generate(model="google/gemini-3.1-flash-tts", voice="Kore", prompt="Welcome to Cut.Pro. Your video is ready.")
+print(voice["output"]["url"])  # MP3
+```
+
+## Models and prices
+
+```python
+catalog = cutpro.models.list(kind="video", endpoint="generations")
+featured = cutpro.models.featured(kind="image")
+
+# Public price list, no key needed: credits, dollars and reais per unit.
+prices = CutPro().models.prices()
+```
+
+| Kind | Model ids |
+|---|---|
+| Video | [`bytedance/seedance-2.5`](https://cut.pro/en/models/seedance-2-5), [`bytedance/seedance-2`](https://cut.pro/en/models/seedance-2), [`alibaba/wan-3`](https://cut.pro/en/models/wan-3), [`kling/kling-o3-pro`](https://cut.pro/en/models/kling-o3-pro), [`kling/kling-3-pro`](https://cut.pro/en/models/kling-3-pro), [`google/veo-3.1`](https://cut.pro/en/models/veo-3-1), [`google/gemini-omni-flash-1.1`](https://cut.pro/en/models/gemini-omni-flash-1-1), [`xai/grok-imagine-video-1.5`](https://cut.pro/en/models/grok-imagine-video-1-5), [`minimax/h3`](https://cut.pro/en/models/h3) |
+| Image | [`google/nano-banana-pro`](https://cut.pro/en/models/nano-banana-pro), [`bytedance/seedream-5-pro`](https://cut.pro/en/models/seedream-5-pro), [`alibaba/qwen-image-3-pro`](https://cut.pro/en/models/qwen-image-3-pro), [`openai/gpt-image-2.5`](https://cut.pro/en/models/gpt-image-2-5), [`xai/grok-imagine-image-2`](https://cut.pro/en/models/grok-imagine-image-2) |
+| Voice | [`google/gemini-3.1-flash-tts`](https://cut.pro/en/models/gemini-3-1-flash-tts), [`minimax/speech-2.8-hd`](https://cut.pro/en/models/speech-2-8-hd) |
+
+The full catalog is in `models.list()` and at [cut.pro/en/models](https://cut.pro/en/models). Prices change: read them from the API, never hard-code them.
+
+## Errors
+
+```python
+from cutpro import CutProError
+
+try:
+    cutpro.generations.generate(model="bytedance/seedance-2.5", prompt="a dog surfing", seconds=3)
+except CutProError as error:
+    if error.code == "INSUFFICIENT_CREDITS":
+        print("Top up at", error.extra["top_up_url"])
+    elif error.code == "SECONDS_INVALID":
+        print("Allowed seconds:", error.extra["allowed"])
+    else:
+        raise
+```
+
+`code` is stable, `status` is the HTTP status and `extra` has what to act on. `status` is `0` for errors raised by the client: `WAIT_TIMEOUT`, `INSECURE_BASE_URL`, `INSECURE_DOWNLOAD_URL`, or a generation that ended `failed` (its `error_code` becomes `code`, and the credits come back on their own). Full list in the [error catalog](https://cut.pro/docs/en/errors).
+
+## asyncio
+
+`AsyncCutPro` has the same methods. Waiting never blocks the event loop, so FastAPI, aiohttp or a Jupyter notebook can run many generations at once.
+
+```python
+import asyncio
+from cutpro import AsyncCutPro
+
+async def main() -> None:
+    cutpro = AsyncCutPro()
+    videos = await asyncio.gather(*(cutpro.generations.generate(model="bytedance/seedance-2-fast", prompt=p, seconds=5) for p in ["a dog surfing", "a cat skating"]))
+    print([video["output"]["url"] for video in videos])
+
+asyncio.run(main())
+```
+
+## Download to a file
+
+```python
+cutpro.generations.download_to(video["id"], "dog.mp4")  # streams to disk, never holds the whole file in memory
+```
+
+## Webhooks
+
+```python
+from cutpro import verify_webhook
+
+secret = cutpro.generations.webhook_secret()  # store it with your other secrets
+
+# In your webhook route, with the raw body before any JSON parsing:
+if not verify_webhook(raw_body, headers.get("CutPro-Signature"), secret):
+    return 401
+```
+
+It checks the HMAC of the exact body, refuses signatures older than five minutes and compares in constant time.
+
+## A browser app on your Python server
+
+The key spends credits, so it never goes to a page. `proxy_request` forwards only what a generation needs (models, prices, quote, create, get) with the key added on your server. With FastAPI:
+
+```python
+from fastapi import FastAPI, Request, Response
+from cutpro import proxy_request
+
+app = FastAPI()
+
+@app.api_route("/api/cutpro/{path:path}", methods=["GET", "POST"])
+async def cutpro_proxy(path: str, request: Request) -> Response:
+    if not is_signed_in(request):  # whoever reaches this route spends your credits
+        return Response(status_code=401)
+    status, body = proxy_request(request.method, f"/{path}", body=await request.body(), headers=dict(request.headers), query=request.url.query)
+    return Response(body, status_code=status, media_type="application/json")
+```
+
+The page uses the JavaScript SDK with `new CutPro({ baseURL: "/api/cutpro" })`.
+
+## Options
+
+```python
+CutPro(
+    api_key="...",          # defaults to CUTPRO_API_KEY
+    workspace_id="...",     # only for a key that reaches more than one workspace
+    base_url="https://api.cut.pro/api/v1",
+    timeout=90.0,           # seconds per HTTP request
+    max_retries=2,
+    transport=my_transport, # (method, url, headers, body, timeout) -> (status, headers, body): plug in httpx or requests, or stub it in tests
+)
+```
+
+## Security and reliability
+
+- The key only travels in the `X-Api-Key` header, never in a URL, and redirects are refused so it never follows one to another host. `repr(client)` never shows it.
+- `base_url` must be `https`, except on localhost.
+- `generations.create` sends an `Idempotency-Key` (a fresh UUID unless you pass one), so a retry or a repeated call never charges twice.
+- Network errors, `429` and `5xx` are retried twice with backoff, honoring `Retry-After`; uploads are never retried.
+- Waiting uses the server's long poll instead of hammering it.
+
+## Links
+
+- [Generation guide](https://cut.pro/docs/en/generations) and [API reference](https://cut.pro/docs/reference)
+- [Node SDK](https://github.com/getcutpro/sdk-js), [Vercel AI SDK provider](https://github.com/getcutpro/ai-sdk-provider), [n8n node](https://github.com/getcutpro/n8n-nodes-cutpro), [examples](https://github.com/getcutpro/examples)
+
+## Em português
+
+Instala igual com pip, uv, Poetry, PDM, Pipenv e em ambientes Anaconda ou Miniconda (`pip install cutpro`). Tem cliente síncrono e assíncrono (`AsyncCutPro`), verificação de webhook e proxy para usar no navegador sem expor a chave.
+
+SDK oficial da Cut.Pro para Python: uma chave de API para Seedance 2.5, Wan 3, Kling O3, Veo 3.1, Nano Banana Pro, Seedream 5, GPT Image, Grok Imagine, MiniMax e vozes do Gemini TTS. Preço por segundo de vídeo, por imagem ou por 1.000 caracteres de voz, em reais: veja a [tabela de preços ao vivo](https://cut.pro/pt-BR/models). Pague com Pix ou cartão, com nota fiscal para empresas. Toda conta começa com créditos grátis.
+
+```python
+from cutpro import CutPro
+
+cutpro = CutPro()  # lê CUTPRO_API_KEY
+voz = cutpro.generations.generate(model="google/gemini-3.1-flash-tts", voice="Kore", prompt="Olá! Seu vídeo está pronto.")
+print(voz["output"]["url"])
+```
+
+Crie a chave em [cut.pro/studio/me/api-keys](https://cut.pro/studio/me/api-keys). Guia em português: [cut.pro/docs/generations](https://cut.pro/docs/generations). Páginas dos modelos: [Seedance 2.5](https://cut.pro/pt-BR/models/seedance-2-5), [Wan 3](https://cut.pro/pt-BR/models/wan-3), [Nano Banana Pro](https://cut.pro/pt-BR/models/nano-banana-pro), [Gemini 3.1 Flash TTS](https://cut.pro/pt-BR/models/gemini-3-1-flash-tts).
+
+## License
+
+MIT

cutpro-0.1.0/README.md

@@ -0,0 +1,236 @@
+# Cut.Pro Python SDK: Seedance, Wan, Kling, Veo and Nano Banana API in Python
+
+[![PyPI](https://img.shields.io/pypi/v/cutpro)](https://pypi.org/project/cutpro/) [![license](https://img.shields.io/pypi/l/cutpro)](LICENSE)
+
+One API key for video, image and voice models: Seedance 2.5, Wan 3, Kling O3, Veo 3.1, Gemini Omni Flash, Nano Banana Pro, Seedream 5, Qwen Image, GPT Image, Grok Imagine, MiniMax and Gemini TTS voices. Priced per second of video, per image or per 1,000 characters of voice, in reais and dollars: see the [live price list](https://cut.pro/en/models). Pay with Pix or card; companies get an invoice.
+
+Python 3.9 to 3.13, standard library only (no dependencies), fully typed (`py.typed`), sync and asyncio. A pure wheel, so it installs the same way in any environment:
+
+```bash
+pip install cutpro          # pip, virtualenv, Anaconda and Miniconda environments
+uv add cutpro               # uv
+poetry add cutpro           # Poetry
+pdm add cutpro              # PDM
+pipenv install cutpro       # Pipenv
+```
+
+## Quickstart
+
+Create a key at [cut.pro/studio/me/api-keys](https://cut.pro/studio/me/api-keys) and set `CUTPRO_API_KEY`. Every account starts with free credits.
+
+```python
+from cutpro import CutPro
+
+cutpro = CutPro()  # reads CUTPRO_API_KEY
+
+video = cutpro.generations.generate(
+    model="bytedance/seedance-2.5",
+    prompt="a golden retriever surfing a wave at sunset, cinematic",
+    seconds=5,
+    resolution="720p",
+    aspect_ratio="16:9",
+)
+print(video["output"]["url"], video["credits_charged"], "credits")
+```
+
+`generate()` quotes the request, starts it with the quoted total and waits until it is ready. Each step is also its own call.
+
+## Seedance API in Python, step by step
+
+```python
+import uuid
+
+quote = cutpro.generations.quote(model="bytedance/seedance-2.5", prompt="a dog surfing", seconds=5)
+print(quote["credits"], "credits")  # show the price and wait for a yes
+
+started = cutpro.generations.create(
+    model="bytedance/seedance-2.5",
+    prompt="a dog surfing",
+    seconds=5,
+    credits=quote["credits"],
+    idempotency_key=str(uuid.uuid4()),
+)
+
+done = cutpro.generations.wait(started["id"], timeout=600)
+if done["status"] == "ready":
+    print(done["output"]["url"])
+```
+
+- `create()` without `credits` quotes first and agrees to that total. With `credits`, the price is checked on the server: if it changed, nothing is charged and you get `PRICE_CHANGED` with the new total in `extra["credits"]`.
+- `idempotency_key`: repeating the same request with the same key within 24 hours never charges twice.
+- `webhook_url="https://..."` gets a signed POST when the generation ends, instead of waiting.
+
+## Wan 3 image to video
+
+```python
+clip = cutpro.generations.generate(
+    model="alibaba/wan-3",
+    mode="image",
+    image_urls=["https://your-cdn.com/product.jpg"],
+    prompt="the camera slowly orbits the product, soft studio light",
+    seconds=5,
+    resolution="720p",
+)
+```
+
+Local file? `media = cutpro.media.upload(open("product.jpg", "rb").read(), filename="product.jpg", content_type="image/jpeg")` and send `image_ids=[media["id"]]`.
+
+## Nano Banana Pro image with references
+
+```python
+image = cutpro.generations.generate(
+    model="google/nano-banana-pro",
+    mode="references",
+    image_urls=["https://your-cdn.com/person.jpg", "https://your-cdn.com/jacket.jpg"],
+    prompt="the person from the first image wearing the jacket from the second, street photo",
+    aspect_ratio="4:5",
+)
+```
+
+## Gemini TTS voice
+
+```python
+voices = cutpro.models.list(id="google/gemini-3.1-flash-tts")["models"][0]["voices"]
+print([voice["id"] for voice in voices])
+
+voice = cutpro.generations.generate(model="google/gemini-3.1-flash-tts", voice="Kore", prompt="Welcome to Cut.Pro. Your video is ready.")
+print(voice["output"]["url"])  # MP3
+```
+
+## Models and prices
+
+```python
+catalog = cutpro.models.list(kind="video", endpoint="generations")
+featured = cutpro.models.featured(kind="image")
+
+# Public price list, no key needed: credits, dollars and reais per unit.
+prices = CutPro().models.prices()
+```
+
+| Kind | Model ids |
+|---|---|
+| Video | [`bytedance/seedance-2.5`](https://cut.pro/en/models/seedance-2-5), [`bytedance/seedance-2`](https://cut.pro/en/models/seedance-2), [`alibaba/wan-3`](https://cut.pro/en/models/wan-3), [`kling/kling-o3-pro`](https://cut.pro/en/models/kling-o3-pro), [`kling/kling-3-pro`](https://cut.pro/en/models/kling-3-pro), [`google/veo-3.1`](https://cut.pro/en/models/veo-3-1), [`google/gemini-omni-flash-1.1`](https://cut.pro/en/models/gemini-omni-flash-1-1), [`xai/grok-imagine-video-1.5`](https://cut.pro/en/models/grok-imagine-video-1-5), [`minimax/h3`](https://cut.pro/en/models/h3) |
+| Image | [`google/nano-banana-pro`](https://cut.pro/en/models/nano-banana-pro), [`bytedance/seedream-5-pro`](https://cut.pro/en/models/seedream-5-pro), [`alibaba/qwen-image-3-pro`](https://cut.pro/en/models/qwen-image-3-pro), [`openai/gpt-image-2.5`](https://cut.pro/en/models/gpt-image-2-5), [`xai/grok-imagine-image-2`](https://cut.pro/en/models/grok-imagine-image-2) |
+| Voice | [`google/gemini-3.1-flash-tts`](https://cut.pro/en/models/gemini-3-1-flash-tts), [`minimax/speech-2.8-hd`](https://cut.pro/en/models/speech-2-8-hd) |
+
+The full catalog is in `models.list()` and at [cut.pro/en/models](https://cut.pro/en/models). Prices change: read them from the API, never hard-code them.
+
+## Errors
+
+```python
+from cutpro import CutProError
+
+try:
+    cutpro.generations.generate(model="bytedance/seedance-2.5", prompt="a dog surfing", seconds=3)
+except CutProError as error:
+    if error.code == "INSUFFICIENT_CREDITS":
+        print("Top up at", error.extra["top_up_url"])
+    elif error.code == "SECONDS_INVALID":
+        print("Allowed seconds:", error.extra["allowed"])
+    else:
+        raise
+```
+
+`code` is stable, `status` is the HTTP status and `extra` has what to act on. `status` is `0` for errors raised by the client: `WAIT_TIMEOUT`, `INSECURE_BASE_URL`, `INSECURE_DOWNLOAD_URL`, or a generation that ended `failed` (its `error_code` becomes `code`, and the credits come back on their own). Full list in the [error catalog](https://cut.pro/docs/en/errors).
+
+## asyncio
+
+`AsyncCutPro` has the same methods. Waiting never blocks the event loop, so FastAPI, aiohttp or a Jupyter notebook can run many generations at once.
+
+```python
+import asyncio
+from cutpro import AsyncCutPro
+
+async def main() -> None:
+    cutpro = AsyncCutPro()
+    videos = await asyncio.gather(*(cutpro.generations.generate(model="bytedance/seedance-2-fast", prompt=p, seconds=5) for p in ["a dog surfing", "a cat skating"]))
+    print([video["output"]["url"] for video in videos])
+
+asyncio.run(main())
+```
+
+## Download to a file
+
+```python
+cutpro.generations.download_to(video["id"], "dog.mp4")  # streams to disk, never holds the whole file in memory
+```
+
+## Webhooks
+
+```python
+from cutpro import verify_webhook
+
+secret = cutpro.generations.webhook_secret()  # store it with your other secrets
+
+# In your webhook route, with the raw body before any JSON parsing:
+if not verify_webhook(raw_body, headers.get("CutPro-Signature"), secret):
+    return 401
+```
+
+It checks the HMAC of the exact body, refuses signatures older than five minutes and compares in constant time.
+
+## A browser app on your Python server
+
+The key spends credits, so it never goes to a page. `proxy_request` forwards only what a generation needs (models, prices, quote, create, get) with the key added on your server. With FastAPI:
+
+```python
+from fastapi import FastAPI, Request, Response
+from cutpro import proxy_request
+
+app = FastAPI()
+
+@app.api_route("/api/cutpro/{path:path}", methods=["GET", "POST"])
+async def cutpro_proxy(path: str, request: Request) -> Response:
+    if not is_signed_in(request):  # whoever reaches this route spends your credits
+        return Response(status_code=401)
+    status, body = proxy_request(request.method, f"/{path}", body=await request.body(), headers=dict(request.headers), query=request.url.query)
+    return Response(body, status_code=status, media_type="application/json")
+```
+
+The page uses the JavaScript SDK with `new CutPro({ baseURL: "/api/cutpro" })`.
+
+## Options
+
+```python
+CutPro(
+    api_key="...",          # defaults to CUTPRO_API_KEY
+    workspace_id="...",     # only for a key that reaches more than one workspace
+    base_url="https://api.cut.pro/api/v1",
+    timeout=90.0,           # seconds per HTTP request
+    max_retries=2,
+    transport=my_transport, # (method, url, headers, body, timeout) -> (status, headers, body): plug in httpx or requests, or stub it in tests
+)
+```
+
+## Security and reliability
+
+- The key only travels in the `X-Api-Key` header, never in a URL, and redirects are refused so it never follows one to another host. `repr(client)` never shows it.
+- `base_url` must be `https`, except on localhost.
+- `generations.create` sends an `Idempotency-Key` (a fresh UUID unless you pass one), so a retry or a repeated call never charges twice.
+- Network errors, `429` and `5xx` are retried twice with backoff, honoring `Retry-After`; uploads are never retried.
+- Waiting uses the server's long poll instead of hammering it.
+
+## Links
+
+- [Generation guide](https://cut.pro/docs/en/generations) and [API reference](https://cut.pro/docs/reference)
+- [Node SDK](https://github.com/getcutpro/sdk-js), [Vercel AI SDK provider](https://github.com/getcutpro/ai-sdk-provider), [n8n node](https://github.com/getcutpro/n8n-nodes-cutpro), [examples](https://github.com/getcutpro/examples)
+
+## Em português
+
+Instala igual com pip, uv, Poetry, PDM, Pipenv e em ambientes Anaconda ou Miniconda (`pip install cutpro`). Tem cliente síncrono e assíncrono (`AsyncCutPro`), verificação de webhook e proxy para usar no navegador sem expor a chave.
+
+SDK oficial da Cut.Pro para Python: uma chave de API para Seedance 2.5, Wan 3, Kling O3, Veo 3.1, Nano Banana Pro, Seedream 5, GPT Image, Grok Imagine, MiniMax e vozes do Gemini TTS. Preço por segundo de vídeo, por imagem ou por 1.000 caracteres de voz, em reais: veja a [tabela de preços ao vivo](https://cut.pro/pt-BR/models). Pague com Pix ou cartão, com nota fiscal para empresas. Toda conta começa com créditos grátis.
+
+```python
+from cutpro import CutPro
+
+cutpro = CutPro()  # lê CUTPRO_API_KEY
+voz = cutpro.generations.generate(model="google/gemini-3.1-flash-tts", voice="Kore", prompt="Olá! Seu vídeo está pronto.")
+print(voz["output"]["url"])
+```
+
+Crie a chave em [cut.pro/studio/me/api-keys](https://cut.pro/studio/me/api-keys). Guia em português: [cut.pro/docs/generations](https://cut.pro/docs/generations). Páginas dos modelos: [Seedance 2.5](https://cut.pro/pt-BR/models/seedance-2-5), [Wan 3](https://cut.pro/pt-BR/models/wan-3), [Nano Banana Pro](https://cut.pro/pt-BR/models/nano-banana-pro), [Gemini 3.1 Flash TTS](https://cut.pro/pt-BR/models/gemini-3-1-flash-tts).
+
+## License
+
+MIT

cutpro-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cutpro"
+version = "0.1.0"
+description = "Cut.Pro API client for Python: Seedance, Wan, Kling, Veo, Nano Banana, Seedream, GPT Image and Gemini TTS with one key, priced per second, image or 1,000 characters"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Cut.Pro" }]
+requires-python = ">=3.9"
+dependencies = []
+keywords = ["cutpro", "ai", "api", "sdk", "video-generation", "image-generation", "text-to-speech", "text-to-video", "image-to-video", "seedance", "seedance-api", "wan", "kling", "veo", "nano-banana", "seedream", "gpt-image", "gemini-tts"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://cut.pro/docs/en/generations"
+Source = "https://github.com/getcutpro/sdk-python"
+Issues = "https://github.com/getcutpro/sdk-python/issues"
+Prices = "https://cut.pro/en/models"
+
+[dependency-groups]
+dev = ["pytest>=8", "mypy>=1.13"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cutpro"]
+
+[tool.mypy]
+strict = true
+# Every response is parsed JSON, typed by the TypedDict each method returns.
+warn_return_any = false
+files = ["src", "tests"]