Puras SDK Client Reference

puras.Client is the external half of the SDK: call skills you've deployed from your own backend, script, or CI. It's the counterpart to the in-skill runtime — instead of running inside a job, it submits jobs and hands back the result. Both ship in the same pip install puras.

Authenticate with a workspace API key (puras_live_…): pass api_key= or set the PURAS_API_KEY environment variable. Mint a key from the dashboard.

import puras

client = puras.Client(skillpack="<skillpack-id>")   # PURAS_API_KEY from env
out = client.run("ugc-ad", {"product": url, "duration": 15})

Client

Call deployed skills.

Pass a fully-qualified workspace/skillpack/skill path to run/submit (copyable from a skill's page), or set a default skillpack once — a slug or UUID — and call skills by bare name.

Client(api_key: 'str | None' = None, skillpack: 'str | None' = None, *, api_base: 'str | None' = None, timeout: 'float' = 120.0)

Client.get(job_id: 'str') -> 'dict'

Fetch a job by id.

Client.run(skill: 'str', inputs: 'dict | None' = None, *, skillpack: 'str | None' = None, version: 'int | None' = None, timeout: 'float' = 600, poll_interval: 'float' = 2.0) -> 'dict'

Submit + wait, returning the skill's result. Raises JobError if it didn't succeed (including still-running when timeout elapses).

Waiting is client-side polling (poll_interval seconds between checks), so multi-minute media jobs work; timeout defaults to 10 minutes.

skill may be a "workspace/skillpack/skill" path (copyable from the skill's page) or a bare name resolved against the default skillpack.

Pass version=N to pin the run to a specific deployment version of the skillpack; omit it to use the active deployment.

Client.submit(skill: 'str', inputs: 'dict | None' = None, *, skillpack: 'str | None' = None, version: 'int | None' = None, wait: 'bool' = False, timeout: 'int' = 60) -> 'dict'

Submit a job. wait=True blocks server-side up to timeout seconds (the API caps the server-side wait at 60 — short jobs only; for longer runs use run() or wait(), which poll client-side). Returns the job object ({id, status, result, error, …}).

skill may be a fully-qualified path — "workspace/skillpack/skill" (copyable from the skill's page) or "skillpack/skill" for one of your own — in which case the skillpack is taken from the path. A bare skill name uses the default skillpack passed here or to Client(...).

version pins the run to a specific deployment version of the skillpack (e.g. version=3); omit it to use the active deployment, which follows new deploys. Pinning lets you keep running a release you've validated even after newer versions are deployed.

Client.wait(job_id: 'str', *, timeout: 'float' = 600, poll_interval: 'float' = 2.0) -> 'dict'

Poll a job until it reaches a terminal status (succeeded / failed / cancelled) or timeout seconds elapse. Returns the last job object — check status; a job still running at timeout is returned as-is.

Exceptions

PurasAPIError

Non-2xx response from the Puras API.

JobError

A job finished in a non-succeeded state (failed/cancelled/timeout).