TypeScript SDK
@rawframe/sdk for Node.js 20.3 and later.
npm install @rawframe/sdkThe SDK has no dependencies and is ESM only. It's tested on Node.js 20.3 and later. It uses only fetch,
Web Crypto and AbortSignal.any, so other runtimes with those (Bun, Deno, edge runtimes) should work,
but aren't tested yet. Use it on the server: API keys don't belong in browsers.
Client
import { RawFrame } from "@rawframe/sdk";
const rf = new RawFrame({
apiKey: process.env.RAWFRAME_API_KEY, // the default
maxRetries: 2, // retries for connection errors, 429 and 5xx (see Retries)
timeoutMs: 60_000, // per attempt
});| Option | Default | |
|---|---|---|
apiKey | RAWFRAME_API_KEY | Throws if neither is set. |
baseUrl | RAWFRAME_BASE_URL, then https://api.rawframe.dev | |
maxRetries | 2 | What's retried |
timeoutMs | 60000 | Per attempt. |
fetch | global fetch | For proxies or instrumentation. |
Every method takes an optional last argument with signal (an AbortSignal), and creates also take
idempotencyKey.
Methods
| Method | API |
|---|---|
models.list({ type?, mode? }) | GET /v1/models, returns Model[] |
models.get(id) | GET /v1/models/{id} (the id is encoded for you) |
generations.create(body) | POST /v1/generations |
generations.createAndWait(body, { timeoutMs?, pollIntervalMs?, onStatus? }) | create, then wait |
generations.waitForCompletion(idOrGeneration, options) | poll until terminal |
generations.get(id) / cancel(id) | GET / POST .../cancel |
generations.list({ limit?, cursor?, status?, model? }) | one page |
generations.iterate(filters) | async iterator over every page |
generations.stream(id) | async iterator of Server-Sent Events |
uploads.upload(data, { contentType }) | create + PUT + confirm, returns the ready Upload |
uploads.create(body) / get(id) | the two steps separately |
account.balance(), usage(range), exportUsage(range) | balance, usage, CSV text |
account.createTopup(body), account.autoRecharge.get() / update(body) | billing |
webhookEndpoints.create / list / update / delete | webhook endpoints |
webhooks.verify(body, headers, secret) | same as verifyWebhook |
Request and response types are exported too: import type { Generation, Model } from "@rawframe/sdk".
Waiting
createAndWait and waitForCompletion poll every 2 seconds (pollIntervalMs) for up to 15 minutes
(timeoutMs). They resolve with the succeeded generation, and throw:
GenerationFailedErrorif it endsfailedorcanceled.err.generationhas the details.GenerationTimeoutErrorif the timeout passes first. The generation keeps running; waiting again or a webhook will still see it finish.
const video = await rf.generations.createAndWait(
{ model: "bytedance/seedance-2.5", prompt: "..." },
{ timeoutMs: 10 * 60_000, onStatus: (g) => console.log(g.status) },
);Errors
| Class | When |
|---|---|
RawFrameError | The API returned an error: status, type, code, param, requestId, retryAfter |
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
verifyWebhook(rawBody, headers, secret) checks the signature and timestamp and returns the typed
event. headers can be a Headers object or Node's req.headers. See Webhooks.
Lower-level access
rf.client is the client generated from the OpenAPI spec, and the generated functions are what the
methods above call. You shouldn't need it, but it's there for anything new in the API before the SDK
wraps it.