Python SDK
rawframe for Python 3.11+, sync and async.
pip install rawframePython 3.11 or later. Its dependencies are httpx and attrs.
Clients
from rawframe import AsyncRawFrame, RawFrame
rf = RawFrame(
api_key=None, # default: the RAWFRAME_API_KEY environment variable
max_retries=2, # retries for connection errors, 429 and 5xx (see Retries)
timeout=60.0, # seconds per attempt
)AsyncRawFrame takes the same options and has the same methods as coroutines, with async for for
iterate and stream. Both clients can be used as context managers (with / async with) to close
their connection pools.
| Option | Default | |
|---|---|---|
api_key | RAWFRAME_API_KEY | Raises ValueError if neither is set. |
base_url | RAWFRAME_BASE_URL, then https://api.rawframe.dev | |
max_retries | 2 | What's retried |
timeout | 60.0 | Seconds, per attempt. |
transport | httpx default | An httpx transport, for proxies or tests. |
Creates take idempotency_key=.
Methods
| Method | API |
|---|---|
models.list(type=, mode=) | GET /v1/models, returns a list of Model |
models.get(model_id) | GET /v1/models/{id} |
generations.create(model, prompt, **fields) | POST /v1/generations |
generations.create_and_wait(model, prompt, timeout=, poll_interval=, on_status=, **fields) | create, then wait |
generations.wait_for_completion(generation_or_id, timeout=900, poll_interval=2) | poll until terminal |
generations.get(id) / cancel(id) | GET / POST .../cancel |
generations.list(limit=, cursor=, status=, model=) | one page |
generations.iterate(limit=, status=, model=) | every page |
generations.stream(id) | Server-Sent Events, as GenerationEvents |
uploads.upload(data, content_type=) | bytes, a path or a binary file; returns the ready Upload |
uploads.create(...) / get(id) | the two steps separately |
account.balance(), usage(start=, end=, group_by=), export_usage(start=, end=) | balance, usage, CSV text |
account.create_topup(...), account.auto_recharge.get() / update(...) | billing |
webhook_endpoints.create / list / update / delete | webhook endpoints |
**fields are the other request fields: mode, references, params, provider_options, metadata.
uploads.upload("frame.png") guesses the content type from the file name.
Responses are typed models generated from the OpenAPI spec, in rawframe.types. A few attribute
names get an underscore to avoid Python keywords and builtins: generation.type_, event.type_. Optional
fields that weren't returned are UNSET, which is falsy.
Waiting
create_and_wait and wait_for_completion poll every 2 seconds for up to 15 minutes. They return the
succeeded generation, and raise:
GenerationFailedErrorif it endsfailedorcanceled.err.generationhas the details.GenerationTimeoutErrorif the timeout passes first. The generation keeps running.
video = rf.generations.create_and_wait(
model="bytedance/seedance-2.5",
prompt="...",
timeout=600,
on_status=lambda g: print(g.status),
)Errors
| Exception | When |
|---|---|
RawFrameError | The API returned an error: status, type, code, param, request_id, retry_after |
APIConnectionError | No response: DNS, connection reset, or timeout |
GenerationFailedError | A waited-on generation failed or was canceled |
GenerationTimeoutError | Waiting gave up |
WebhookVerificationError | A webhook didn't verify |
Webhooks
verify_webhook(raw_body, headers, secret) checks the signature and timestamp and returns the typed
event. headers is any mapping of header names to values. See Webhooks.