jamframe 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- jamframe-0.1.0/.gitignore +9 -0
- jamframe-0.1.0/CHANGELOG.md +21 -0
- jamframe-0.1.0/LICENSE +21 -0
- jamframe-0.1.0/PKG-INFO +510 -0
- jamframe-0.1.0/README.md +477 -0
- jamframe-0.1.0/pyproject.toml +53 -0
- jamframe-0.1.0/spec/openapi.yaml +6114 -0
- jamframe-0.1.0/src/jamframe/__init__.py +69 -0
- jamframe-0.1.0/src/jamframe/_async_client.py +944 -0
- jamframe-0.1.0/src/jamframe/_base.py +458 -0
- jamframe-0.1.0/src/jamframe/_brand.py +19 -0
- jamframe-0.1.0/src/jamframe/_client.py +916 -0
- jamframe-0.1.0/src/jamframe/_version.py +1 -0
- jamframe-0.1.0/src/jamframe/errors.py +189 -0
- jamframe-0.1.0/src/jamframe/py.typed +0 -0
- jamframe-0.1.0/src/jamframe/types.py +1343 -0
- jamframe-0.1.0/src/jamframe/webhooks.py +194 -0
- jamframe-0.1.0/tests/__init__.py +0 -0
- jamframe-0.1.0/tests/conftest.py +171 -0
- jamframe-0.1.0/tests/test_ai_workflows.py +279 -0
- jamframe-0.1.0/tests/test_async.py +111 -0
- jamframe-0.1.0/tests/test_client.py +380 -0
- jamframe-0.1.0/tests/test_errors_and_retries.py +223 -0
- jamframe-0.1.0/tests/test_live_smoke.py +162 -0
- jamframe-0.1.0/tests/test_spec.py +354 -0
- jamframe-0.1.0/tests/test_webhooks.py +150 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0
|
|
4
|
+
|
|
5
|
+
The first release.
|
|
6
|
+
|
|
7
|
+
- Render templates to PNG, JPEG, WebP, PDF and MP4: carousels, Smart Resize
|
|
8
|
+
(one size or several), translation, link lifetimes (`expires_in`), and the
|
|
9
|
+
experimental PDF options `cmyk` and `compress`.
|
|
10
|
+
- Render jobs: `render_async`, `render_and_wait`, `render_jobs.get` and `wait`.
|
|
11
|
+
- Templates: list, search and get your own and the template library's;
|
|
12
|
+
design new ones with AI (`designs.generate`, `generate_async`, `design_jobs`).
|
|
13
|
+
- The render log, signed render URLs.
|
|
14
|
+
- Workflows: list, get, create, update, delete, run (and wait), runs, cancel,
|
|
15
|
+
a new incoming webhook URL.
|
|
16
|
+
- Social: accounts, posts (create, list, get, cancel, retry) and analytics
|
|
17
|
+
(overview, daily, insights).
|
|
18
|
+
- AI tools: remove a background, transcribe speech into subtitles, AI status.
|
|
19
|
+
- Webhook subscriptions, and signature checks for deliveries
|
|
20
|
+
(`construct_event`, `verify_signature`).
|
|
21
|
+
- Sync and async clients, typed errors, retries for rate limits and safe calls.
|
jamframe-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Alphacloud Technologies Pte Ltd
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
jamframe-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,510 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: jamframe
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Python client for the JamFrame API: render templates to images, carousels, PDFs and videos, design templates with AI, run workflows and post to social accounts.
|
|
5
|
+
Project-URL: Homepage, https://jamframe.com/
|
|
6
|
+
Project-URL: Documentation, https://app.jamframe.com/docs/api
|
|
7
|
+
Project-URL: Repository, https://github.com/JamFrame-com/jamframe-python
|
|
8
|
+
Project-URL: Issues, https://github.com/JamFrame-com/jamframe-python/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/JamFrame-com/jamframe-python/blob/main/CHANGELOG.md
|
|
10
|
+
Author-email: Alphacloud Technologies Pte Ltd <hello@jamframe.com>
|
|
11
|
+
License-Expression: MIT
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
Keywords: api client,carousel,image generation,jamframe,pdf,social media,templates,video
|
|
14
|
+
Classifier: Development Status :: 4 - Beta
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
25
|
+
Classifier: Typing :: Typed
|
|
26
|
+
Requires-Python: >=3.9
|
|
27
|
+
Requires-Dist: httpx<1,>=0.24
|
|
28
|
+
Provides-Extra: dev
|
|
29
|
+
Requires-Dist: mypy>=1.5; extra == 'dev'
|
|
30
|
+
Requires-Dist: pytest>=7; extra == 'dev'
|
|
31
|
+
Requires-Dist: pyyaml>=6; extra == 'dev'
|
|
32
|
+
Description-Content-Type: text/markdown
|
|
33
|
+
|
|
34
|
+
# jamframe (Python)
|
|
35
|
+
|
|
36
|
+
The Python client for the [JamFrame](https://jamframe.com) API: render your
|
|
37
|
+
templates to images, carousels, PDFs and MP4 videos, design new templates
|
|
38
|
+
with AI, run workflows, post to social accounts and read their analytics,
|
|
39
|
+
and verify webhooks.
|
|
40
|
+
|
|
41
|
+
- Python 3.9 or later. One dependency: [httpx](https://www.python-httpx.org/).
|
|
42
|
+
- Sync (`Client`) and async (`AsyncClient`) clients with the same methods.
|
|
43
|
+
- Fully typed (`py.typed`, `TypedDict` for every API shape, `mypy --strict` clean).
|
|
44
|
+
- Retries 429s (honouring `Retry-After`) and, for idempotent calls only,
|
|
45
|
+
5xx answers, connection errors and timeouts.
|
|
46
|
+
|
|
47
|
+
API reference: [app.jamframe.com/docs/api](https://app.jamframe.com/docs/api)
|
|
48
|
+
(the OpenAPI spec is [app.jamframe.com/openapi.yaml](https://app.jamframe.com/openapi.yaml)).
|
|
49
|
+
The [Node.js SDK](https://github.com/JamFrame-com/jamframe-node) has the same surface.
|
|
50
|
+
|
|
51
|
+
## Install
|
|
52
|
+
|
|
53
|
+
```sh
|
|
54
|
+
pip install jamframe
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Quick start
|
|
58
|
+
|
|
59
|
+
Create an API key in the app under **Developers → API Keys** (it starts with
|
|
60
|
+
`jf_live_`), then:
|
|
61
|
+
|
|
62
|
+
```python
|
|
63
|
+
from jamframe import Client
|
|
64
|
+
|
|
65
|
+
client = Client(api_key="jf_live_...") # or set JAMFRAME_API_KEY
|
|
66
|
+
|
|
67
|
+
result = client.render(
|
|
68
|
+
"clx8m2k3p0001abcd1234efgh", # a template id (yours or a library one)
|
|
69
|
+
{"title": "Summer sale ends Sunday", "title.color": "#FF4D4F"},
|
|
70
|
+
response={"format": "png", "scale": 2},
|
|
71
|
+
)
|
|
72
|
+
print(result["data"]["content"]) # the image URL
|
|
73
|
+
print(result["data"]["credits"]) # 1
|
|
74
|
+
print(result["warnings"]) # e.g. modification keys that matched nothing
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
`Client()` with no arguments reads `JAMFRAME_API_KEY` and, if set,
|
|
78
|
+
`JAMFRAME_BASE_URL`. `base_url` is the API's origin
|
|
79
|
+
(`https://api.jamframe.com`) or its root (`…/v1`); both work, and so does
|
|
80
|
+
the older `https://app.jamframe.com/api/v1`.
|
|
81
|
+
|
|
82
|
+
Use it as a context manager (or call `close()`) to release connections:
|
|
83
|
+
|
|
84
|
+
```python
|
|
85
|
+
with Client() as client:
|
|
86
|
+
print(client.whoami()) # {'workspaceId': '…', 'username': 'Jane Doe'}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Templates
|
|
90
|
+
|
|
91
|
+
```python
|
|
92
|
+
# Your workspace's templates, newest first (one page).
|
|
93
|
+
page = client.designs.list(limit=25)
|
|
94
|
+
page["designs"], page["pagination"]["nextCursor"]
|
|
95
|
+
|
|
96
|
+
# Every template, page after page.
|
|
97
|
+
for design in client.designs.iter():
|
|
98
|
+
print(design["id"], design["name"], design["orientation"])
|
|
99
|
+
|
|
100
|
+
# The template library (ready-made templates any workspace can render).
|
|
101
|
+
for design in client.designs.iter(source="library"):
|
|
102
|
+
...
|
|
103
|
+
|
|
104
|
+
# A picker's search box: names containing the text, ignoring case (either source).
|
|
105
|
+
# Each design has its page count and `animated` (a video template: render it as mp4).
|
|
106
|
+
for design in client.designs.iter(source="library", q="reel"):
|
|
107
|
+
print(design["name"], design["pages"], "video" if design["animated"] else "still")
|
|
108
|
+
|
|
109
|
+
# What a template takes: parameters (keys for `modifications`), page count, saved sizes.
|
|
110
|
+
detail = client.designs.get("clx8m2k3p0002abcd1234efgh")
|
|
111
|
+
for p in detail["parameters"]:
|
|
112
|
+
print(p["key"], p["type"], p["pages"], p["example"])
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Modification keys: `title` sets every layer (and `{{title}}` placeholder)
|
|
116
|
+
with that key, `page2@title` only on page 2, `title.color` overrides a style
|
|
117
|
+
property, `page2@title.color` both. See the API reference for the full list
|
|
118
|
+
(`fontSize`, `hidden`, `fill`, `audio`, `audio.volume`, `subtitles`, …).
|
|
119
|
+
|
|
120
|
+
### Design a template with AI
|
|
121
|
+
|
|
122
|
+
```python
|
|
123
|
+
# Waits for the design (usually 10–40 s); 15 to 30 AI credits, refunded if it fails.
|
|
124
|
+
job = client.designs.generate(
|
|
125
|
+
"Announce our summer sale, 30% off everything this weekend. Bold and playful.",
|
|
126
|
+
size="instagram-portrait", # or "linkedin-carousel" with pages=5, or "1200x630"
|
|
127
|
+
# brand=False, or {"colors": ["#0b1f4d", "#ff6b5b"], "fonts": ["Poppins"]}; default: your brand library
|
|
128
|
+
)
|
|
129
|
+
job["design"]["id"] # render it like any other template
|
|
130
|
+
job["design"]["parameters"] # [{'key': 'title', …}, {'key': 'photo', …}]
|
|
131
|
+
job["design"]["editorUrl"] # open it in the editor
|
|
132
|
+
|
|
133
|
+
# Or start it and come back later (webhook_url= is called when it ends).
|
|
134
|
+
started = client.designs.generate_async("A teaser video for our app launch", video=True)
|
|
135
|
+
done = client.design_jobs.wait(started["jobId"])
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
A failed generation raises `DesignJobFailedError` (`.code`, `.message`, `.job`).
|
|
139
|
+
|
|
140
|
+
## Rendering
|
|
141
|
+
|
|
142
|
+
Credits: 1 per image or PDF page, 1 per second of video (rounded up),
|
|
143
|
+
charged only when a render succeeds.
|
|
144
|
+
|
|
145
|
+
```python
|
|
146
|
+
# A carousel: one URL per page.
|
|
147
|
+
r = client.render("tpl_id", {"title": "5 ways to brew", "page2@title": "1. Grind fresh"},
|
|
148
|
+
response={"format": "jpeg", "quality": 90})
|
|
149
|
+
r["data"]["content"] # ['https://…-p1.jpg', 'https://…-p2.jpg', …]
|
|
150
|
+
|
|
151
|
+
# A library template by its slug, as a PDF of pages 1 and 2, with links that work for an hour.
|
|
152
|
+
client.render("tool-quote-card-paper", {"quote": "Stay curious"},
|
|
153
|
+
response={"format": "pdf", "includePages": [1, 2]}, expires_in=3600)
|
|
154
|
+
|
|
155
|
+
# Smart Resize: one size …
|
|
156
|
+
client.render("tpl_id", {"title": "Hi"}, response={"format": "png", "size": "story"})
|
|
157
|
+
# … or several in one call (content is one entry per size).
|
|
158
|
+
r = client.render("tpl_id", {"title": "Hi"}, response={"sizes": ["original", "story", "1200x630"]})
|
|
159
|
+
for entry in r["data"]["content"]:
|
|
160
|
+
print(entry["size"], entry["width"], entry["height"], entry.get("url") or entry.get("urls"))
|
|
161
|
+
r["data"]["urls"] # every file's link in one list
|
|
162
|
+
|
|
163
|
+
# Translate every text layer with AI (AI credits; cached per text and language).
|
|
164
|
+
client.render("tpl_id", translate=True, lang="es", ai={"onError": "fallback"})
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
`jamframe.file_urls(content)` flattens any `content` (a URL, a list of URLs
|
|
168
|
+
or the per-size entries) into a list of URLs. File links work for
|
|
169
|
+
`expires_in` seconds (5 minutes by default, at most 7 days;
|
|
170
|
+
`data["expiresAt"]` says until when).
|
|
171
|
+
|
|
172
|
+
**Experimental, PDF only:** `response={"format": "pdf", "cmyk": True}` (or
|
|
173
|
+
`{"profile": "gracol2013"}`) converts the colours to CMYK for print, and
|
|
174
|
+
`"compress": True` (or `{"preset": "printer"}`) makes the file smaller.
|
|
175
|
+
Their options and output may still change.
|
|
176
|
+
|
|
177
|
+
### Videos and render jobs
|
|
178
|
+
|
|
179
|
+
MP4 renders, and any render sent as `async`, run as **render jobs**.
|
|
180
|
+
|
|
181
|
+
```python
|
|
182
|
+
# Simplest: render() waits. The API answers an MP4 within 90 s, or hands
|
|
183
|
+
# back a job, which render() then polls (up to wait_timeout seconds).
|
|
184
|
+
video = client.render("tpl_id", {"title": "New menu"}, response={"format": "mp4"})
|
|
185
|
+
video["data"]["content"], video["data"]["duration"]
|
|
186
|
+
|
|
187
|
+
# Queue it and get the job id at once …
|
|
188
|
+
job = client.render_async("tpl_id", {"title": "New menu"}, response={"format": "mp4"},
|
|
189
|
+
webhook_url="https://example.com/hooks/render-done")
|
|
190
|
+
job["jobId"] # poll it, or wait for the webhook_url callback
|
|
191
|
+
|
|
192
|
+
# … poll it yourself …
|
|
193
|
+
client.render_jobs.get(job["jobId"])["progress"] # 0 to 1
|
|
194
|
+
|
|
195
|
+
# … or wait for it (polls every 1 s, then 1.5x longer each time, at most 5 s).
|
|
196
|
+
done = client.render_jobs.wait(job["jobId"], timeout=600)
|
|
197
|
+
done["result"]["content"]
|
|
198
|
+
|
|
199
|
+
# Queue and wait in one call.
|
|
200
|
+
done = client.render_and_wait("tpl_id", {"title": "New menu"}, response={"format": "mp4"})
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
A failed job raises `RenderJobFailedError` (`.code`, `.message`, `.job`;
|
|
204
|
+
failed renders cost nothing). Running past the timeout raises
|
|
205
|
+
`WaitTimeoutError` (`.job_id`, `.last_job`); the job keeps running, so you
|
|
206
|
+
can wait again.
|
|
207
|
+
|
|
208
|
+
The `webhook_url` callback is not signed. Treat it as a hint and fetch the
|
|
209
|
+
job with `render_jobs.get()` before trusting it, or subscribe to the signed
|
|
210
|
+
`render.completed` / `render.failed` webhook events instead.
|
|
211
|
+
|
|
212
|
+
## Render log
|
|
213
|
+
|
|
214
|
+
```python
|
|
215
|
+
page = client.renders.list(status="failed", limit=10)
|
|
216
|
+
page["totals"]["creditsRemaining"] # this billing period
|
|
217
|
+
for render in client.renders.iter(design_id="tpl_id"):
|
|
218
|
+
print(render["id"], render["status"], [o["url"] for o in render["outputs"]])
|
|
219
|
+
|
|
220
|
+
# One render by id (the `renderId` of a render, or of a job's `result`).
|
|
221
|
+
render = client.renders.get(result["data"]["renderId"])
|
|
222
|
+
render["status"], render["credits"], render["outputs"]
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
## Signed URLs
|
|
226
|
+
|
|
227
|
+
A tamper-proof link that renders when opened, for `<img src>`, emails and
|
|
228
|
+
`og:image`. Creating it is free; opening it renders (and caches) the image.
|
|
229
|
+
|
|
230
|
+
```python
|
|
231
|
+
signed = client.signed_urls.create("tpl_id", {"title": "How we cut render times"},
|
|
232
|
+
response={"format": "png"}, expires_in=30 * 24 * 3600)
|
|
233
|
+
signed["data"]["url"]
|
|
234
|
+
|
|
235
|
+
client.signed_urls.rotate_key() # revoke every signed URL of the workspace
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
## Workflows
|
|
239
|
+
|
|
240
|
+
Workflows render a template for each row of a Google Sheet, a CSV or XLSX
|
|
241
|
+
file, an Airtable table or a webhook, and deliver the files. Build them in
|
|
242
|
+
the app (or with `workflows.create()`), then run them from code.
|
|
243
|
+
|
|
244
|
+
```python
|
|
245
|
+
workflows = client.workflows.list()
|
|
246
|
+
|
|
247
|
+
# Run one and wait for it to end; each row costs render credits.
|
|
248
|
+
run = client.workflows.run_and_wait(workflows[0]["id"], max_rows=2) # a test run
|
|
249
|
+
run["status"] # 'succeeded', 'partial', 'failed' or 'canceled' (check it)
|
|
250
|
+
[row["urls"] for row in run["rows"]] # each row's files
|
|
251
|
+
|
|
252
|
+
# A webhook-payload source: send the rows yourself.
|
|
253
|
+
client.workflows.run("wf_id", payload=[{"Quote": "Stay curious", "Author": "Ada"}])
|
|
254
|
+
|
|
255
|
+
for r in client.workflows.runs.iter("wf_id"):
|
|
256
|
+
print(r["id"], r["status"])
|
|
257
|
+
client.workflows.runs.cancel("wf_id", "run_id")
|
|
258
|
+
client.workflows.update("wf_id", status="active") # turns on its schedule or trigger
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
## Social posts
|
|
262
|
+
|
|
263
|
+
Accounts are connected in the app, which shows the networks you can
|
|
264
|
+
connect. Posting costs no credits; a template render costs the usual credits.
|
|
265
|
+
|
|
266
|
+
```python
|
|
267
|
+
accounts = client.social.accounts.list()
|
|
268
|
+
ids = [a["id"] for a in accounts if a["status"] == "active"]
|
|
269
|
+
|
|
270
|
+
created = client.social.posts.create(
|
|
271
|
+
template_id="tpl_id",
|
|
272
|
+
modifications={"title": "Spring sale"},
|
|
273
|
+
response={"format": "jpeg"},
|
|
274
|
+
accounts=ids,
|
|
275
|
+
caption="Spring sale starts today #sale",
|
|
276
|
+
scheduled_at="2026-11-10T09:00",
|
|
277
|
+
timezone="Europe/Paris",
|
|
278
|
+
# options={"pinterest": {"boardId": "…"}, "tiktok": {"draft": True}, "buffer": {"mode": "next"}},
|
|
279
|
+
)
|
|
280
|
+
post = created["post"] # created["checks"]: per-account warnings
|
|
281
|
+
|
|
282
|
+
client.social.posts.get(post["id"])["targets"] # each account's status and permalink
|
|
283
|
+
client.social.posts.list(status="attention") # failed or partly failed
|
|
284
|
+
client.social.posts.cancel(post["id"])
|
|
285
|
+
client.social.posts.retry(post["id"]) # or target_id="…" for one account
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
`create()` takes the API body as a dict, as keyword arguments, or both;
|
|
289
|
+
`template_id`, `render_id`, `media_urls` and `scheduled_at` are accepted for
|
|
290
|
+
`templateId`, `renderId`, `mediaUrls` and `scheduledAt`.
|
|
291
|
+
|
|
292
|
+
### Analytics
|
|
293
|
+
|
|
294
|
+
```python
|
|
295
|
+
import datetime
|
|
296
|
+
|
|
297
|
+
overview = client.social.analytics.overview(from_=datetime.date(2026, 10, 1), to="2026-10-31",
|
|
298
|
+
platform=["instagram", "linkedin"])
|
|
299
|
+
overview["totals"]["impressions"], overview["change"]["engagement"] # change in % from the period before
|
|
300
|
+
days = client.social.analytics.daily(from_="2026-10-01")["days"]
|
|
301
|
+
insights = client.social.analytics.insights()
|
|
302
|
+
insights["bestTimes"]["bestWeekday"], insights["bestTimes"]["bestHour"]
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
A metric is `None` when the platforms in scope don't report it. (`from_` has
|
|
306
|
+
an underscore because `from` is a Python keyword.)
|
|
307
|
+
|
|
308
|
+
## AI tools
|
|
309
|
+
|
|
310
|
+
```python
|
|
311
|
+
from pathlib import Path
|
|
312
|
+
|
|
313
|
+
# Cut the subject out of a picture (a URL or a file); a transparent PNG in your brand library. 1 AI credit.
|
|
314
|
+
cutout = client.ai.remove_background(file=Path("product.jpg"))
|
|
315
|
+
client.render("tpl_id", {"photo": cutout["url"]})
|
|
316
|
+
|
|
317
|
+
# Subtitles from speech (a URL or a file, up to 100 MB). 1 AI credit per minute of audio.
|
|
318
|
+
subs = client.ai.transcribe(url="https://example.com/voiceover.mp3", style="short")
|
|
319
|
+
client.render("tpl_id", {"subtitles": subs["cues"]}, response={"format": "mp4"})
|
|
320
|
+
|
|
321
|
+
# Whether AI is available, the prices and your AI credits this period. Free.
|
|
322
|
+
client.ai.status()["credits"]["remaining"]
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
`file=` takes bytes, a `pathlib.Path` or a file opened in binary mode
|
|
326
|
+
(`open("product.jpg", "rb")`).
|
|
327
|
+
|
|
328
|
+
## Webhooks
|
|
329
|
+
|
|
330
|
+
Subscribe a URL to events (`design.created`, `design.updated`,
|
|
331
|
+
`design.deleted`, `render.completed`, `render.failed`,
|
|
332
|
+
`social.post.published`, `social.post.failed`, `workflow.run.completed`,
|
|
333
|
+
`workflow.run.failed`):
|
|
334
|
+
|
|
335
|
+
```python
|
|
336
|
+
created = client.webhooks.subscriptions.create(
|
|
337
|
+
"https://example.com/hooks/jamframe", ["render.completed", "render.failed"]
|
|
338
|
+
)
|
|
339
|
+
secret = created["signingSecret"] # shown once: store it
|
|
340
|
+
client.webhooks.subscriptions.test(created["subscription"]["id"], "render.completed")
|
|
341
|
+
client.webhooks.subscriptions.delete(created["subscription"]["id"])
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
Verify every delivery against the **raw** body:
|
|
345
|
+
|
|
346
|
+
```python
|
|
347
|
+
# Flask
|
|
348
|
+
from flask import Flask, request, abort
|
|
349
|
+
from jamframe import WebhookSignatureError, construct_event
|
|
350
|
+
|
|
351
|
+
app = Flask(__name__)
|
|
352
|
+
|
|
353
|
+
@app.post("/hooks/jamframe")
|
|
354
|
+
def jamframe_hook():
|
|
355
|
+
try:
|
|
356
|
+
event = construct_event(request.get_data(), request.headers, SECRET)
|
|
357
|
+
except WebhookSignatureError:
|
|
358
|
+
abort(400)
|
|
359
|
+
# Deliveries are at-least-once: deduplicate on request.headers["X-Webhook-Delivery"].
|
|
360
|
+
if event["type"] == "render.completed":
|
|
361
|
+
print(event["data"]["result"]["content"])
|
|
362
|
+
return "", 204
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
```python
|
|
366
|
+
# FastAPI
|
|
367
|
+
from fastapi import FastAPI, HTTPException, Request
|
|
368
|
+
from jamframe import verify_signature
|
|
369
|
+
|
|
370
|
+
app = FastAPI()
|
|
371
|
+
|
|
372
|
+
@app.post("/hooks/jamframe")
|
|
373
|
+
async def jamframe_hook(request: Request):
|
|
374
|
+
body = await request.body()
|
|
375
|
+
if not verify_signature(body, request.headers.get("x-webhook-signature", ""), SECRET):
|
|
376
|
+
raise HTTPException(400)
|
|
377
|
+
...
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
`verify_signature(payload, header, secret, tolerance=300)` returns a bool;
|
|
381
|
+
`construct_event` raises `WebhookSignatureError` and returns the parsed event.
|
|
382
|
+
`header` is the `X-Webhook-Signature` value or the request's headers;
|
|
383
|
+
`secret` may be a list (old and new while you rotate). Signatures older or
|
|
384
|
+
newer than `tolerance` seconds are refused (replay protection).
|
|
385
|
+
|
|
386
|
+
## Errors
|
|
387
|
+
|
|
388
|
+
Every error answer raises a subclass of `jamframe.APIError` with `status`,
|
|
389
|
+
`code` (the API's `error`, e.g. `QUOTA_EXCEEDED`), `message` (safe to show
|
|
390
|
+
to users) and `detail`:
|
|
391
|
+
|
|
392
|
+
| Status | Exception | Typical `code` |
|
|
393
|
+
| --- | --- | --- |
|
|
394
|
+
| 400 | `BadRequestError` | `VALIDATION_ERROR`, `INVALID_REQUEST`, `WEBHOOK_URL_INVALID` |
|
|
395
|
+
| 401 | `AuthenticationError` | `MISSING_API_KEY`, `INVALID_API_KEY`, `EXPIRED_API_KEY` |
|
|
396
|
+
| 402 | `PaymentRequiredError` | `QUOTA_EXCEEDED`, `WORKSPACE_QUOTA_EXCEEDED`, `AI_CREDITS_EXCEEDED`, `PLAN_LIMIT_EXCEEDED`, `WEBHOOK_LIMIT_REACHED` |
|
|
397
|
+
| 403 | `PermissionDeniedError` | `ORG_ON_HOLD`, `ORG_SUSPENDED` |
|
|
398
|
+
| 404 | `NotFoundError` | `NOT_FOUND` |
|
|
399
|
+
| 409 | `ConflictError` | `CONFLICT` |
|
|
400
|
+
| 422 | `UnprocessableEntityError` | `VALIDATION_ERROR` (a media URL that won't load), `AI_CONTENT_REFUSED`, `AI_BAD_REQUEST` |
|
|
401
|
+
| 429 | `RateLimitError` (`.retry_after`) | `RATE_LIMITED`, `AI_RATE_LIMITED` |
|
|
402
|
+
| 5xx | `InternalServerError` | `INTERNAL`, `AI_BAD_OUTPUT`, `AI_UPSTREAM_ERROR`, `AI_UNAVAILABLE`, `VIDEO_UNAVAILABLE`, `AI_TIMEOUT` |
|
|
403
|
+
|
|
404
|
+
A body that isn't the API's JSON envelope (a proxy's HTML page) still
|
|
405
|
+
raises the right class, with `code` `HTTP_<status>`. Network failures raise
|
|
406
|
+
`APIConnectionError`, timeouts `APITimeoutError`. A failed render job raises
|
|
407
|
+
`RenderJobFailedError`, a failed AI design `DesignJobFailedError`, a wait
|
|
408
|
+
past its timeout `WaitTimeoutError`. Everything derives from
|
|
409
|
+
`jamframe.SDKError`.
|
|
410
|
+
|
|
411
|
+
```python
|
|
412
|
+
from jamframe import PaymentRequiredError, BadRequestError
|
|
413
|
+
|
|
414
|
+
try:
|
|
415
|
+
client.render("tpl_id", {"titel": "typo is a warning, not an error"})
|
|
416
|
+
except PaymentRequiredError as e:
|
|
417
|
+
print("Out of credits:", e.detail.get("remaining"))
|
|
418
|
+
except BadRequestError as e:
|
|
419
|
+
print(e.code, e.message, e.detail.get("issues"))
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
## Retries and timeouts
|
|
423
|
+
|
|
424
|
+
- **429** is retried for every call (`max_retries`, default 2): the rate
|
|
425
|
+
limiter refuses a request before anything happens. The client waits for
|
|
426
|
+
`Retry-After` (or `detail.retryAfter`); if that's over 60 s it raises
|
|
427
|
+
`RateLimitError` instead.
|
|
428
|
+
- **5xx, connection errors and timeouts** are retried only for idempotent
|
|
429
|
+
calls: reads, deletes, `whoami()`, `signed_urls.create()` and
|
|
430
|
+
`workflows.update()`. A render, an AI call, a social post, a workflow run
|
|
431
|
+
or a subscription isn't retried: it may have happened before the error.
|
|
432
|
+
- Backoff is 0.5 s, 1 s, 2 s … (at most 8 s), with jitter.
|
|
433
|
+
- `timeout` (default 120 s) is per HTTP request. It must cover a synchronous
|
|
434
|
+
MP4, which the API holds for up to 90 s. Waiting for a job has its own
|
|
435
|
+
`timeout` / `wait_timeout` (default 600 s).
|
|
436
|
+
|
|
437
|
+
```python
|
|
438
|
+
client = Client(timeout=30, max_retries=4, user_agent="my-app/1.2")
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
`user_agent` is prepended to `jamframe-python/<version>`. Pass
|
|
442
|
+
`http_client=httpx.Client(...)` (or `httpx.AsyncClient` for the async
|
|
443
|
+
client) for proxies, custom TLS or transports; the SDK won't close a client
|
|
444
|
+
you pass in.
|
|
445
|
+
|
|
446
|
+
## Async
|
|
447
|
+
|
|
448
|
+
```python
|
|
449
|
+
import asyncio
|
|
450
|
+
from jamframe import AsyncClient
|
|
451
|
+
|
|
452
|
+
async def main():
|
|
453
|
+
async with AsyncClient() as client:
|
|
454
|
+
job = await client.render_and_wait("tpl_id", {"title": "Hi"}, response={"format": "mp4"})
|
|
455
|
+
async for design in client.designs.iter(source="library"):
|
|
456
|
+
print(design["name"])
|
|
457
|
+
|
|
458
|
+
asyncio.run(main())
|
|
459
|
+
```
|
|
460
|
+
|
|
461
|
+
## Why httpx
|
|
462
|
+
|
|
463
|
+
One dependency buys a lot here: the same request code drives a sync and an
|
|
464
|
+
async client, timeouts are real (connect, read, write and pool), connections
|
|
465
|
+
are pooled and kept alive across calls, and `httpx.MockTransport` lets the
|
|
466
|
+
tests run the real client code against a fake API with no server. The
|
|
467
|
+
standard library's `urllib` has no async client, no keep-alive pooling and
|
|
468
|
+
coarse timeouts, so it would mean either a sync-only SDK or a second HTTP
|
|
469
|
+
stack for async.
|
|
470
|
+
|
|
471
|
+
## Development
|
|
472
|
+
|
|
473
|
+
```sh
|
|
474
|
+
uv sync --extra dev # or: python -m venv .venv && pip install -e ".[dev]"
|
|
475
|
+
uv run pytest # unit tests (no network: httpx.MockTransport)
|
|
476
|
+
uv run mypy # strict type check of src/jamframe
|
|
477
|
+
```
|
|
478
|
+
|
|
479
|
+
`tests/test_spec.py` checks the SDK against the API spec in
|
|
480
|
+
[`spec/openapi.yaml`](spec/openapi.yaml): every endpoint has a method (or is
|
|
481
|
+
skipped on purpose), the types have exactly the spec's fields and enum
|
|
482
|
+
values, and the async client has the same methods as the sync one.
|
|
483
|
+
`python scripts/update_spec.py` downloads the live spec; CI does that every
|
|
484
|
+
Monday, so a new API feature shows up as a failing check.
|
|
485
|
+
|
|
486
|
+
The live smoke test runs only when `JAMFRAME_SMOKE_API_KEY` is set. It
|
|
487
|
+
renders 2 PNGs of a library template (2 credits), lists designs and
|
|
488
|
+
renders, signs a URL, reads AI status, workflows and analytics, creates and
|
|
489
|
+
deletes a webhook subscription, and posts to an active *sandbox* social
|
|
490
|
+
account if the workspace has one:
|
|
491
|
+
|
|
492
|
+
```sh
|
|
493
|
+
JAMFRAME_SMOKE_API_KEY=jf_live_... JAMFRAME_SMOKE_BASE_URL=https://api.jamframe.com \
|
|
494
|
+
uv run pytest tests/test_live_smoke.py -s
|
|
495
|
+
```
|
|
496
|
+
|
|
497
|
+
Use a throwaway key and revoke it afterwards.
|
|
498
|
+
|
|
499
|
+
## Releasing
|
|
500
|
+
|
|
501
|
+
1. Update `version` in `pyproject.toml` and `src/jamframe/_version.py` (a
|
|
502
|
+
test checks they match) and add the release to [CHANGELOG.md](CHANGELOG.md).
|
|
503
|
+
2. Commit, then tag the commit with the bare version (`0.1.1`) and push the tag.
|
|
504
|
+
3. [`publish.yml`](.github/workflows/publish.yml) runs the checks, builds,
|
|
505
|
+
publishes to TestPyPI, then (after approval in the `pypi` environment)
|
|
506
|
+
to PyPI, through trusted publishing: no token is stored anywhere.
|
|
507
|
+
|
|
508
|
+
## License
|
|
509
|
+
|
|
510
|
+
[MIT](LICENSE)
|