Cuddler Platform SDK

Release candidate; npm/PyPI publication is pending registry authentication and release verification. Source is maintained in the private Cuddler repository; no public source repository is required.

This client, intended to run in a developer's server environment, uses the native USD Platform API at https://api.cuddler.ai/v1. It supports video, images, speech, music, models, voices, balance, usage and the create/get/complete upload protocol. Media transfer is explicit: use the returned signed URL without an Authorization header. No provider key is required.

TypeScript / JavaScript

import Cuddler from '@cuddler/platform';
const client = new Cuddler({ apiKey: process.env.CUDDLER_API_KEY });
const quote = await client.videos.estimate({
  model: 'seedance-2.5', mode: 'text', variant: 'default',
  duration: 4, resolution: '480p', aspect_ratio: '16:9', generate_audio: false,
});
const job = await client.videos.createAndWait({
  model: 'seedance-2.5', mode: 'text', duration: 4, resolution: '480p',
  aspect_ratio: '16:9', generate_audio: false,
  prompt: 'An original blue clay robot waving.', max_usd: '1.00',
}, { idempotencyKey: 'my-persisted-operation-001' });
if (job.status !== 'succeeded') throw new Error(job.status);

images, speech, and music have the same create/retrieve/list/estimate/wait methods. Cancellation is available for videos, speech and music; images cannot be canceled. The server's current catalog and quotes determine available models and parameters. TypeScript request/response types come from the repository's generated OpenAPI contract.

Python

from cuddler import Cuddler
with Cuddler() as client:  # reads CUDDLER_API_KEY
    models = client.models.list()
    job = client.videos.retrieve('vid_REPLACE_WITH_YOUR_JOB_ID')

Python uses create_and_wait, idempotency_key, timeout and poll_interval. It is a synchronous httpx client; use a worker thread when calling it from an async app.

Recovery and spending

• Every generation requires a positive decimal-string max_usd.
• Each new create gets a fresh key. Persist and explicitly reuse a key and identical request body for a durable business operation; otherwise another create is a new job.
• POST calls are never retried automatically, including estimates and cancel calls.
• On uncertain submission, CuddlerError.idempotencyKey (Python: idempotency_key) carries the original key and outcomeUnknown / outcome_unknown is true. Reconcile or replay that exact operation; do not create a new key blindly.
• GET retries respect Retry-After (at most two retries by default). A delay over 60 seconds returns the error to the caller rather than retrying early.
• Waiting returns terminal failed/canceled jobs as well as successes. A polling timeout includes jobId / job_id; resume with retrieve/wait, never with a new create. An in-flight HTTP read may finish after the polling deadline.
• Keys remain server-side. The SDK does not write credentials, prompts or replay records to disk. Applications are responsible for durable operation identity and recovery.

CLI

Use CUDDLER_API_KEY in the environment; API keys are not accepted as command arguments.

npx @cuddler/platform models
npx @cuddler/platform videos create --json request.json --idempotency-key episode-001 --wait

The CLI exits nonzero for failed/canceled jobs and emits safe recovery metadata on errors.

The Python distribution also installs cuddler-platform; it does not require Node.js. For a local candidate wheel (PyPI installation becomes available after publication):

python -m pip install ./cuddler-0.1.0-py3-none-any.whl
cuddler-platform --help
python -m cuddler models
python -m cuddler videos create --json request.json --idempotency-key episode-001 --wait

Both distributions use the same command name. Install Python into a virtual environment, or use python -m cuddler to select it explicitly. The commands, JSON result output and safe recovery error fields match the npm CLI. Use --json for private prompt content so it does not appear in shell history or process arguments. File transfer uses the returned signed URL without sending the API credential to the media host.

Build and release boundary

The npm source package has a private workspace name because the platform web app already uses @cuddler/platform internally. node scripts/build.mjs produces a separate publishable dist manifest named @cuddler/platform, with only SDK code, contract types and docs. The Python source is in packages/platform-sdk-python-public and builds the package cuddler. The existing private adapter cores in Draft #5979 remain separate and unchanged.

The SDK and CLI only implement API types, HTTP requests, queries, polling, error handling and recovery of the original operation. Model scheduling, server authorization, quota and settlement decisions, and provider credentials remain in the service. Published packages must run without access to this private repository and must not contain private backend implementation, runtime credentials or user data. JavaScript and Python client files in distributed packages remain inspectable; a private source repository does not hide them.

Distribution terms and publication status

SDK and CLI packages are distributed under the MIT License. Keep the bundled LICENSE and copyright notice when copying or redistributing the software. The development repository remains private; this does not restrict the rights granted for the SDK files included in the packages. The license covers the distributed SDK, not private backend code, service access, account credentials or API usage charges.

Both LICENSE files, the JavaScript source and generated package metadata, and Python pyproject.toml declare MIT. Before release, rebuild and inspect both archives and record their hashes against the private source commit. Public source hosting and npm provenance are not prerequisites for this phase. Installers need no private-repository access.

Registry identities, package permissions and release authorization must be verified. After publication, verify clean installation of both SDKs and CLIs from the official npm and PyPI registries. Reuse matching live acceptance evidence; local builds are not proof of registry publication. Do not add paid generation tasks for these documentation changes.