fcaai 0.4.0__tar.gz

fcaai-0.4.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to the `fcaai` Python package. Prices are always USD.
+
+## 0.4.0 — 2026-10-30
+
+Full parity with the public `/v1` REST API.
+
+- **Multi-step templates:** `templates.run_package(slug, values, wait=…)`, `templates.get_run(run_id, wait=…)`, `templates.cancel_run(run_id)`,
+  `templates.wait_run(run_id)`. `templates.run()` now raises `FcaaiError` `template_run` (status 202, the run in `err.body`) when a
+  template turns out to be multi-step, instead of polling the wrong endpoint.
+- `templates.run(slug, values, model=…, brand_kit_id=…, project=…)` — run on another allowed model (`Template.models`), apply a style kit,
+  file the output into an Architecture Studio project (response `arch_project`).
+- `Template` gains `models`, `studio`, `subcategory`, `tags`, `package` and `is_package`; `TemplateInput` gains `role`, `unit`, `placeholder`.
+- **Voices:** `voices.list()`, `voices.clone(files, name=…, consent=True, consent_version=…)` (multipart, never retried),
+  `voices.rename(id, name)`, `voices.delete(id)`; `models.voice_styles(locale=…, category=…)`.
+- **Elements & style kits:** `elements.list(kind=…, q=…, limit=…, cursor=…)`, `style_kits.list(q=…)`.
+- `generations.create(…, brand_kit_id=…, external_user_id=…)`.
+- **Reseller:** `reseller.subtenants.list()`, `reseller.subtenants.create(name, …)` and `reseller.subtenants.create_key(id, name, …)`
+  (both never retried), `reseller.usage(from_=…, to=…)`.
+- **Architecture Studio projects:** `architecture_projects.list/create/get/add_item` (same `/v1/architecture/projects` paths as the
+  TypeScript SDK `architectureProjects`); `add_compliance_label/list_compliance_labels/revoke_compliance_label` ("Representative image"
+  labels, free); `product_list` (billed by tokens, never retried) / `list_product_lists` / `get_product_list(format="csv")`.
+- Docstrings for `generations.list` and `account.usage`; `models.get(…, mask=True)` documented.
+- Packaging: MIT `LICENSE` file, `py.typed` marker (PEP 561), Python 3.9–3.13 classifiers, project URLs.
+
+## 0.3.0 — 2026-10-15
+
+- Canvas surfaces, same `/v1` paths as the TypeScript SDK 0.3: `timelines.create/get/preview/approve/unapprove/final/cut/act/wait`,
+  `farm.jobs.list/get/pause/resume`, `community.list/get`, `approvals.list/get/decide`, `plans.read` (never retried — billed per read),
+  `panoramas.finish`, `video_edits.create` (returns a `Generation`), `flows.list/get/run/get_run/wait/cancel`.
+- Per-request `max_retries` override in the transport.
+
+## 0.2.0 — 2026-09-28
+
+- `audio.speech/sfx/music`, `model3d.from_image`, `images.create` (+ native `images.generate` with `resolution="4k"`, `count`),
+  `templates.list/get/run`, `models.voices`, `models.list(type=)` server-side.
+- Typed `Output` / `Voice` / `Template` dataclasses; `Generation.outputs` with preview URLs. `wait()` unchanged.
+
+## 0.1.0
+
+- First release: generations, uploads (simple + resumable chunked), account, webhooks (+ signature verification), chat completions,
+  OpenAI-compatible image generation.

fcaai-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FCA Studio LLC
+
+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.

fcaai-0.4.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md CHANGELOG.md LICENSE pyproject.toml
+include fcaai/py.typed
+recursive-include tests *.py
+global-exclude *.py[cod] __pycache__ .pytest_cache .venv .env *.egg-info
+prune .venv
+prune .pytest_cache

fcaai-0.4.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: fcaai
+Version: 0.4.0
+Summary: Official Python client for the fcaai API — image, video, audio, 3D and chat generation behind one key.
+Author: FCA Studio LLC
+License-Expression: MIT
+Project-URL: Homepage, https://fcaai.ai
+Project-URL: Documentation, https://fcaai.ai/docs
+Project-URL: Source, https://fcaai.ai/developers#sdk
+Project-URL: Changelog, https://fcaai.ai/developers#sdk
+Keywords: fcaai,ai,api,sdk,image-generation,video-generation,text-to-speech,3d
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Graphics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# fcaai (Python)
+
+Official Python client for the [fcaai API](https://api.fcaai.ai/docs). Standard library only (no `requests`/`httpx`), Python 3.9+. All prices in USD.
+
+```bash
+pip install fcaai
+export FCAAI_API_KEY=fcaai_live_…
+```
+
+```python
+from fcaai import Fcaai
+
+client = Fcaai()  # reads FCAAI_API_KEY
+
+print(client.models.get("google/nano-banana-pro", resolution="2k")["estimate"]["price_display"])
+
+gen = client.generations.create("google/nano-banana-pro", {"prompt": "a paper plane on a wooden desk", "aspect_ratio": "16:9"})
+gen.wait()                       # long-polls /v1/generations/{id}?wait=60
+print(gen.status, gen.urls, gen.price_usd)
+
+# Files: ≤ 50 MB in one request, bigger ones chunked (8 MB, 3 parallel, resumable with session_id=)
+img = client.uploads.create("room.jpg", "image/jpeg")
+video = client.uploads.create_chunked("walkthrough.mp4", mime="video/mp4", on_progress=lambda s, n: print(s * 100 // n, "%"))
+
+clip = client.generations.create("fca/magic-v3", {"image": img["url"], "prompt": "slow dolly in", "duration": 5}, wait=600)
+```
+
+## Audio, 3D, 4K images and templates (0.2)
+
+```python
+# Text to speech (MP3). Voices: [v.id for v in client.models.voices("minimax/speech-2.8")] → narrator, calm, …
+clip = client.audio.speech("Welcome to the studio.", voice="narrator", wait=True)
+
+# Sound effects: duration in seconds, seamless loop
+rain = client.audio.sfx("rain on a tin roof", duration=6, loop=True, wait=True)
+
+# One object photo → GLB (takes minutes)
+chair = client.model3d.from_image(img["url"], detail="detailed", surface="textured", wait=1800)
+
+# 4K on local models (2K render + detail upscaler), up to 4 outputs
+shots = client.images.create("glass villa, blue hour", model="fca/magic-pro", resolution="4k", count=2, wait=True)
+for o in shots.outputs:          # Output dataclass: url, kind, mime, width, height, thumb_url, card_url, poster_url
+    print(o.url, o.thumb_url)
+
+# Templates
+tpl = client.templates.list()[0]
+print([(i.key, i.type, i.required) for i in tpl.inputs])
+run = client.templates.run(tpl.id, {"photo": img["url"]}, wait=True)
+```
+
+## Canvas: timelines, farm, community, approvals, plans, panoramas, video edits (0.3)
+
+```python
+# Scene timeline: storyboard → cheap previews → approve → full quality → one MP4
+tl = client.timelines.create([{"prompt": "Lina walks into the empty gallery at dawn", "duration": 5}],
+                             {"model": "bytedance/seedance-2.0-fast", "imageModel": "fca/magic-pro", "aspect": "16:9"}, preview=True)
+client.timelines.wait(tl["id"]); client.timelines.approve(tl["id"]); client.timelines.final(tl["id"])
+client.timelines.wait(tl["id"], timeout=3600); client.timelines.cut(tl["id"])
+print(client.timelines.wait(tl["id"])["cut"]["url"])
+
+# Render farm (scenes sent from 3ds Max with the FCA plugin; FcaaiError not_enabled when the farm is off)
+for j in client.farm.jobs.list(status="active"):
+    print(j["id"], j["status"], j["progress"])
+client.farm.jobs.pause("fj_…")    # the reserved amount stays on hold; paused time is not charged
+client.farm.jobs.resume("fj_…")
+
+page = client.community.list(type="flow", category="architecture", sort="popular")
+res = client.approvals.list("<board-id>", status="pending")
+client.approvals.decide("<board-id>", "<request-id>", "<option-id>", "changes", note="Warmer light, please.")
+plan = client.plans.read(img["url"])            # billed per read, never retried
+pano = client.panoramas.finish("https://…/pano.png")  # free
+edit = client.video_edits.create([{"url": "https://fcaai.ai/o/…/clip-1.mp4", "start": 0.5, "end": 4}], transition="fade", wait=True)
+print(edit.urls[0])
+```
+
+## Voices, multi-step templates, elements, style kits, reseller (0.4)
+
+```python
+# Clone your own voice (free; speech is billed as usual). Consent is required.
+info = client.voices.list()
+me = client.voices.clone(["take1.mp3", "take2.mp3"], name="My voice", consent=True,
+                         consent_version=info["clone"]["consent_version"])
+client.audio.speech("Hello from my own voice.", voice=me["id"], model="<speech-model-with-cloned-voices>", wait=True)
+styles = client.models.voice_styles(locale="en")    # ready-made speaking styles → styles["param"]
+
+# Multi-step templates (Template.is_package) run as one template run
+tpl = client.templates.get("<package-slug>")
+run = client.templates.run_package(tpl.id, {"photo": img["url"]}, wait=True)
+print(run["status"], run["price_usd"], [o["url"] for o in run["outputs"]])
+# client.templates.get_run(run_id, wait=30) · client.templates.cancel_run(run_id)
+
+# Single-step template on another allowed model, with a style kit, filed into an Architecture Studio project
+kit = client.style_kits.list()[0]
+g = client.templates.run("<slug>", {"photo": img["url"]}, model=tpl.models[-1]["id"], brand_kit_id=kit["id"], project="<project-id>")
+
+# Element library (characters, products, places, materials) → references added server-side
+lina = client.elements.list(kind="character", q="lina")["data"][0]
+client.generations.create("fca/magic-pro", {"prompt": "@lina reading in a cafe", "element_ids": [lina["id"]]},
+                          brand_kit_id=kit["id"], external_user_id="customer-42")
+
+# Reseller keys (scope reseller:manage)
+acme = client.reseller.subtenants.create("Acme Studio", retail_markup=1.5)
+key = client.reseller.subtenants.create_key(acme["id"], "server", mode="live")   # full key shown only here
+print(client.reseller.usage(from_="2026-10-01", to="2026-10-31")["totals"])
+```
+
+`images.generate(prompt, size=…, n=…)` stays OpenAI-compatible (returns a dict); passing `resolution`, `count`, `aspect_ratio`, `images` or `wait` makes it a native generation.
+
+Also: `generations.get/list(status=, limit=)/cancel`, `account.get/balance/usage(from_=, to=)`, `uploads.create_session/get_session/put_chunk/complete_session/delete_session` (low-level resumable upload), `webhooks.list/create/delete/deliveries`, `chat.completions.create(messages)` (OpenAI schema, `fca/chat`), `images.generate(prompt, size=…)`.
+
+Errors raise `fcaai.FcaaiError` (`status`, `type`, `code`, `message`, `request_id`, `doc_url`, `retry_after`, `body`). 429/5xx/network errors are retried (`max_retries=2`) honoring `Retry-After`. `create()` always sends an `Idempotency-Key`, so retries never double-charge.
+
+## Webhooks
+
+```python
+from fcaai import verify_webhook_signature
+
+ok = verify_webhook_signature(secret, request.headers["X-FCAAI-Signature"], request.get_data(), tolerance_sec=300)
+```
+
+## Changelog
+
+Full history in `CHANGELOG.md` (included in the source distribution). **0.4.0** — full `/v1` parity: multi-step template runs, voice cloning + voice styles,
+elements, style kits, reseller sub-tenants/keys/usage, `brand_kit_id` / `external_user_id` on generations, typed package (`py.typed`).
+
+## Tests
+
+```bash
+python -m pytest -q        # or: python -m unittest
+```
+
+License: MIT © 2026 FCA Studio LLC.

fcaai-0.4.0/README.md

@@ -0,0 +1,132 @@
+# fcaai (Python)
+
+Official Python client for the [fcaai API](https://api.fcaai.ai/docs). Standard library only (no `requests`/`httpx`), Python 3.9+. All prices in USD.
+
+```bash
+pip install fcaai
+export FCAAI_API_KEY=fcaai_live_…
+```
+
+```python
+from fcaai import Fcaai
+
+client = Fcaai()  # reads FCAAI_API_KEY
+
+print(client.models.get("google/nano-banana-pro", resolution="2k")["estimate"]["price_display"])
+
+gen = client.generations.create("google/nano-banana-pro", {"prompt": "a paper plane on a wooden desk", "aspect_ratio": "16:9"})
+gen.wait()                       # long-polls /v1/generations/{id}?wait=60
+print(gen.status, gen.urls, gen.price_usd)
+
+# Files: ≤ 50 MB in one request, bigger ones chunked (8 MB, 3 parallel, resumable with session_id=)
+img = client.uploads.create("room.jpg", "image/jpeg")
+video = client.uploads.create_chunked("walkthrough.mp4", mime="video/mp4", on_progress=lambda s, n: print(s * 100 // n, "%"))
+
+clip = client.generations.create("fca/magic-v3", {"image": img["url"], "prompt": "slow dolly in", "duration": 5}, wait=600)
+```
+
+## Audio, 3D, 4K images and templates (0.2)
+
+```python
+# Text to speech (MP3). Voices: [v.id for v in client.models.voices("minimax/speech-2.8")] → narrator, calm, …
+clip = client.audio.speech("Welcome to the studio.", voice="narrator", wait=True)
+
+# Sound effects: duration in seconds, seamless loop
+rain = client.audio.sfx("rain on a tin roof", duration=6, loop=True, wait=True)
+
+# One object photo → GLB (takes minutes)
+chair = client.model3d.from_image(img["url"], detail="detailed", surface="textured", wait=1800)
+
+# 4K on local models (2K render + detail upscaler), up to 4 outputs
+shots = client.images.create("glass villa, blue hour", model="fca/magic-pro", resolution="4k", count=2, wait=True)
+for o in shots.outputs:          # Output dataclass: url, kind, mime, width, height, thumb_url, card_url, poster_url
+    print(o.url, o.thumb_url)
+
+# Templates
+tpl = client.templates.list()[0]
+print([(i.key, i.type, i.required) for i in tpl.inputs])
+run = client.templates.run(tpl.id, {"photo": img["url"]}, wait=True)
+```
+
+## Canvas: timelines, farm, community, approvals, plans, panoramas, video edits (0.3)
+
+```python
+# Scene timeline: storyboard → cheap previews → approve → full quality → one MP4
+tl = client.timelines.create([{"prompt": "Lina walks into the empty gallery at dawn", "duration": 5}],
+                             {"model": "bytedance/seedance-2.0-fast", "imageModel": "fca/magic-pro", "aspect": "16:9"}, preview=True)
+client.timelines.wait(tl["id"]); client.timelines.approve(tl["id"]); client.timelines.final(tl["id"])
+client.timelines.wait(tl["id"], timeout=3600); client.timelines.cut(tl["id"])
+print(client.timelines.wait(tl["id"])["cut"]["url"])
+
+# Render farm (scenes sent from 3ds Max with the FCA plugin; FcaaiError not_enabled when the farm is off)
+for j in client.farm.jobs.list(status="active"):
+    print(j["id"], j["status"], j["progress"])
+client.farm.jobs.pause("fj_…")    # the reserved amount stays on hold; paused time is not charged
+client.farm.jobs.resume("fj_…")
+
+page = client.community.list(type="flow", category="architecture", sort="popular")
+res = client.approvals.list("<board-id>", status="pending")
+client.approvals.decide("<board-id>", "<request-id>", "<option-id>", "changes", note="Warmer light, please.")
+plan = client.plans.read(img["url"])            # billed per read, never retried
+pano = client.panoramas.finish("https://…/pano.png")  # free
+edit = client.video_edits.create([{"url": "https://fcaai.ai/o/…/clip-1.mp4", "start": 0.5, "end": 4}], transition="fade", wait=True)
+print(edit.urls[0])
+```
+
+## Voices, multi-step templates, elements, style kits, reseller (0.4)
+
+```python
+# Clone your own voice (free; speech is billed as usual). Consent is required.
+info = client.voices.list()
+me = client.voices.clone(["take1.mp3", "take2.mp3"], name="My voice", consent=True,
+                         consent_version=info["clone"]["consent_version"])
+client.audio.speech("Hello from my own voice.", voice=me["id"], model="<speech-model-with-cloned-voices>", wait=True)
+styles = client.models.voice_styles(locale="en")    # ready-made speaking styles → styles["param"]
+
+# Multi-step templates (Template.is_package) run as one template run
+tpl = client.templates.get("<package-slug>")
+run = client.templates.run_package(tpl.id, {"photo": img["url"]}, wait=True)
+print(run["status"], run["price_usd"], [o["url"] for o in run["outputs"]])
+# client.templates.get_run(run_id, wait=30) · client.templates.cancel_run(run_id)
+
+# Single-step template on another allowed model, with a style kit, filed into an Architecture Studio project
+kit = client.style_kits.list()[0]
+g = client.templates.run("<slug>", {"photo": img["url"]}, model=tpl.models[-1]["id"], brand_kit_id=kit["id"], project="<project-id>")
+
+# Element library (characters, products, places, materials) → references added server-side
+lina = client.elements.list(kind="character", q="lina")["data"][0]
+client.generations.create("fca/magic-pro", {"prompt": "@lina reading in a cafe", "element_ids": [lina["id"]]},
+                          brand_kit_id=kit["id"], external_user_id="customer-42")
+
+# Reseller keys (scope reseller:manage)
+acme = client.reseller.subtenants.create("Acme Studio", retail_markup=1.5)
+key = client.reseller.subtenants.create_key(acme["id"], "server", mode="live")   # full key shown only here
+print(client.reseller.usage(from_="2026-10-01", to="2026-10-31")["totals"])
+```
+
+`images.generate(prompt, size=…, n=…)` stays OpenAI-compatible (returns a dict); passing `resolution`, `count`, `aspect_ratio`, `images` or `wait` makes it a native generation.
+
+Also: `generations.get/list(status=, limit=)/cancel`, `account.get/balance/usage(from_=, to=)`, `uploads.create_session/get_session/put_chunk/complete_session/delete_session` (low-level resumable upload), `webhooks.list/create/delete/deliveries`, `chat.completions.create(messages)` (OpenAI schema, `fca/chat`), `images.generate(prompt, size=…)`.
+
+Errors raise `fcaai.FcaaiError` (`status`, `type`, `code`, `message`, `request_id`, `doc_url`, `retry_after`, `body`). 429/5xx/network errors are retried (`max_retries=2`) honoring `Retry-After`. `create()` always sends an `Idempotency-Key`, so retries never double-charge.
+
+## Webhooks
+
+```python
+from fcaai import verify_webhook_signature
+
+ok = verify_webhook_signature(secret, request.headers["X-FCAAI-Signature"], request.get_data(), tolerance_sec=300)
+```
+
+## Changelog
+
+Full history in `CHANGELOG.md` (included in the source distribution). **0.4.0** — full `/v1` parity: multi-step template runs, voice cloning + voice styles,
+elements, style kits, reseller sub-tenants/keys/usage, `brand_kit_id` / `external_user_id` on generations, typed package (`py.typed`).
+
+## Tests
+
+```bash
+python -m pytest -q        # or: python -m unittest
+```
+
+License: MIT © 2026 FCA Studio LLC.

fcaai-0.4.0/fcaai/__init__.py

@@ -0,0 +1,10 @@
+"""Official Python client for the fcaai API (https://api.fcaai.ai). Standard library only."""
+from ._errors import FcaaiError, FcaaiTimeoutError
+from .client import (CHUNK_SIZE, DEFAULT_BASE_URL, SIMPLE_UPLOAD_MAX, Fcaai, Generation, Output, Template, TemplateInput, Transport, Voice,
+                     VoiceSample,
+                     __version__, urllib_transport)
+from .webhooks import construct_event, parse_signature_header, sign_webhook_payload, verify_webhook_signature
+
+__all__ = ["Fcaai", "Generation", "Output", "Voice", "Template", "TemplateInput", "FcaaiError", "FcaaiTimeoutError", "verify_webhook_signature", "sign_webhook_payload",
+           "parse_signature_header", "construct_event", "Transport", "VoiceSample", "urllib_transport", "DEFAULT_BASE_URL",
+           "SIMPLE_UPLOAD_MAX", "CHUNK_SIZE", "__version__"]

fcaai-0.4.0/fcaai/_errors.py

@@ -0,0 +1,31 @@
+from typing import Any, Optional
+
+
+class FcaaiError(Exception):
+    """Raised for every non-2xx response (and network failures, status 0)."""
+
+    def __init__(self, message: str, *, status: int = 0, type: str = "api_error", code: str = "error",
+                 request_id: Optional[str] = None, doc_url: Optional[str] = None,
+                 retry_after: Optional[float] = None, body: Any = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.type = type
+        self.code = code
+        self.request_id = request_id
+        self.doc_url = doc_url
+        self.retry_after = retry_after
+        self.body = body
+
+    @property
+    def retryable(self) -> bool:
+        return self.status in (0, 408, 429) or self.status >= 500
+
+    def __repr__(self) -> str:
+        return f"FcaaiError(status={self.status}, code={self.code!r}, message={self.message!r}, request_id={self.request_id!r})"
+
+
+class FcaaiTimeoutError(FcaaiError):
+    def __init__(self, message: str, generation_id: Optional[str] = None) -> None:
+        super().__init__(message, status=0, type="timeout", code="wait_timeout")
+        self.generation_id = generation_id