Replicate

Replicate is the official Node.js/JavaScript client for Replicate, the platform for running open-source machine learning models in the cloud via API. It wraps every major Replicate HTTP endpoint — predictions, models, deployments, trainings, files, hardware, and collections — behind a typed, promise-based interface, so applications can run models like Stable Diffusion or Flux, poll or stream their progress, and handle file inputs/outputs without hand-rolling HTTP calls.

The client is built to work identically across Node.js, Bun, Deno, and edge runtimes such as Cloudflare Workers and Vercel Functions, with dedicated integration test suites verifying each target. It ships first-class TypeScript definitions, automatic retry-with-backoff for rate-limited or failed requests, webhook signature verification, and a FileOutput abstraction that streams generated files (images, audio, etc.) directly as Blob/ReadableStream without requiring callers to write custom polling or download logic.

What You Get

• A Replicate client class covering predictions, models, deployments, trainings, files, hardware, collections, and webhooks in one object
• A high-level run() method that creates a prediction, blocks or polls until completion, and returns typed output — including automatic FileOutput wrapping for URLs/data URIs
• A stream() async generator that yields Server-Sent Events for real-time prediction progress instead of polling
• Built-in automatic retries with exponential backoff for 429/5xx responses, plus webhook signature validation via validateWebhook
• Full TypeScript type definitions (index.d.ts) and verified compatibility across Node.js, Bun, Deno, Cloudflare Workers, and browser bundles

Common Use Cases

• Backend services that run a hosted model (e.g. Stable Diffusion, Flux, Whisper) and return the result to a web or mobile client
• Streaming partial model output to a frontend in real time using replicate.stream() instead of polling for completion
• Serverless/edge functions (Vercel, Cloudflare Workers, AWS Lambda) that call Replicate models without a persistent server
• Webhook-driven pipelines that receive prediction status updates instead of polling, verified with validateWebhook

Under The Hood

Architecture The client class (index.js) instantiates namespaced sub-clients (this.predictions, this.models, this.deployments, etc.) each bound from separate lib/*.js modules via .bind(this), giving each module access to the shared request() method without inheritance. request() centralizes URL building, header injection (auth bearer token, content-type, user-agent), body serialization (JSON or FormData), and retry logic via withAutomaticRetries in lib/util.js. The high-level run() orchestrates predictions.create → wait/poll → transform(output), using ModelVersionIdentifier.parse (lib/identifier.js) to distinguish an “owner/name” ref from an “owner/name:version” ref, and stream() follows an analogous path but yields SSE events from lib/stream.js’s createReadableStream, which conditionally polyfills TextDecoderStream and pulls in a vendored event-source parser. This is a flat, function-composition architecture with no class hierarchy beyond ApiError and Replicate itself — straightforward to extend by adding a new lib/*.js module and binding it in the constructor. Because every resource module depends on this.request(), a breaking change to that one method would ripple across the entire API surface.

Tech Stack TypeScript is used only for type declarations and compile-time checking (tsc), while the implementation itself is plain CommonJS JavaScript, formatted and linted with Biome and validated for package correctness with publint. Tests run through Jest with ts-jest. Runtime dependencies are minimal — only readable-stream as an optional polyfill — with everything else relying on platform-native fetch, ReadableStream, and TextDecoderStream, backed by vendored polyfills (vendor/eventsource-parser, vendor/streams-text-encoding) for environments that lack them. There is no web or ORM framework involved; this is a headless HTTP client targeting Node.js 18+, explicitly tested against Bun and Deno as well.

Code Quality Testing is extensive: the main index.test.ts suite mocks Replicate’s HTTP API with nock across thousands of lines, and seven separate integration-test projects verify real runtime compatibility for Deno, Bun, Cloudflare Workers, browser bundles, ESM, CommonJS, and TypeScript consumption. Error handling is explicit and typed — a dedicated ApiError class carries the original Request/Response objects and is thrown uniformly by request() rather than swallowed, while user-facing validation errors (invalid webhook URL, missing model/version) throw plain Errors with clear messages. Naming is consistent (camelCase methods mirroring REST resource names), JSDoc annotates nearly every exported function with parameter and return types, and CI runs lint (Biome + publint) plus the full test suite on every change.

API Design The library’s core ergonomic win is collapsing Replicate’s async job-based API (create a prediction, poll, fetch the result) into a single await replicate.run(ref, { input }) call, while still exposing the low-level primitives (predictions.create/get/cancel) for callers who need more control. stream() lets consumers for await real-time SSE progress using the same ref/input shape as run(). The FileOutput object’s .blob()/.url() duality avoids forcing every caller to write custom download logic for binary outputs, and the wait: { mode: "block" | "poll", timeout, interval } option gives fine-grained control over blocking behavior via Replicate’s Prefer: wait HTTP header. Documentation and JSDoc are thorough, and onboarding requires only new Replicate({ auth }) plus one .run() call to get a working example — about as low-boilerplate as this class of API-wrapper library gets.