@worldlabsai/client
v0.7.0
Published
TypeScript client for the World Labs Developer API
Readme
@worldlabsai/client
Upload images, submit World Labs tasks, and retrieve typed results with the World Labs Developer API client for JavaScript and TypeScript.
Zero runtime dependencies. The client uses the standard Fetch API and ships as ES modules. It supports Node.js 22+ and other Fetch-compatible runtimes. Keep API keys on your server, out of browser bundles.
Install
Install with npm install @worldlabsai/client.
Use a World Labs Developer API key to authenticate API requests.
Before choosing model inputs or combining tasks, read How To Use Atlas.
Usage
The client provides assets for uploads, tasks for submissions, and
operations for results. This example combines them to estimate camera poses
and depth from a local frame.png, with WLT_API_KEY set on the server:
import { readFile } from "node:fs/promises";
import { assetRef, createClient } from "@worldlabsai/client";
const apiKey = process.env.WLT_API_KEY;
if (!apiKey) throw new Error("Set WLT_API_KEY before running this example");
const wl = createClient({ apiKey });
const image = await wl.assets.upload(await readFile("./frame.png"), {
displayName: "frame.png",
mimeType: "image/png",
});
const operation = await wl.tasks.images2PosedRGBD({
frames: [{ imageAsset: assetRef(image) }],
});
const result = await wl.operations.wait(operation, {
signal: AbortSignal.timeout(120_000),
});
if (result.error) throw new Error(result.error.message ?? "Task failed");
for (const { camera, depth } of result.response?.frames ?? []) {
console.log(camera.extrinsics.position, depth.depthAsset.url);
}assetRef converts an uploaded asset into a task input. Task methods infer the
operation's response type, which operations.wait preserves. Other tasks use
the same submission and polling pattern.
See examples/ for runnable scripts.
posing.ts accepts a local file or a downloadable image
URL and documents its environment variables.
Operations and errors
A finished task can still have result.error; check that field before using
result.response, as in the example above.
HTTP failures reject with ApiError. Its response.status and body provide
the status code and error details. Network failures from JSON API requests reject
with NetworkError, with the underlying error in cause. Aborts reject with the
signal's reason.
Aborting stops the local request or polling; it does not cancel the server-side
task. Keep operation.id to check its status later with operations.get(id).
Polling has no default overall timeout. pollIntervalMs sets the pause between
incomplete polls and defaults to 1,000 milliseconds.
With { retryNetworkErrors: true }, operations.wait keeps polling the same
operation after network failures until it completes or the caller's signal
aborts, including a signal with a timeout. Network failures reject by default.
It retries HTTP 502, 503, and 504 polling failures up to three times in a row,
with pollIntervalMs between attempts. A successful poll resets the retry count.
Other failures, including authentication and HTTP 429 rate limits, reject without
retrying. Network retries also use pollIntervalMs between attempts.
Task submissions retry network failures and HTTP 429, 502, 503, and 504 up to
three times. Every attempt sends the same idempotency key and body. Retries use
exponential backoff with jitter and wait at least as long as Retry-After when
the server supplies it. A response naming a wait longer than ten seconds, such
as a concurrency cap or an hourly quota, rejects at once so you can surface it.
Aborting the submission also stops retries. Validation and authentication
failures are not retried. Pass { retry: false } to disable
submission retries.
If you call the task method again yourself, reuse its idempotencyKey. Each
method call otherwise generates a new key. Passing { wait: true } when
submitting asks the server to wait up to its own limit; it can still return an
unfinished operation.
Client options
Uploads accept bytes or a Blob. Set mimeType for byte arrays or a Blob
without a type. Signed storage uploads use the configured fetch but bypass
API middleware and API-key authentication.
| Option | Use |
| ------------ | --------------------------------------------------------------------------------------------------------------------- |
| apiKey | Your Developer API key, or a function that returns a key or a promise of one before each API request. |
| baseUrl | API base URL. Defaults to https://api.atlas.worldlabs.ai. |
| fetch | Custom Fetch implementation for API requests and uploads. Defaults to globalThis.fetch. |
| middleware | Wrap API requests for logging or retries. The first supplied middleware runs outermost, after API-key authentication. |
| userAgent | Product tokens that name your app, such as my-app/1.2.0. They are sent before the client's own in User-Agent. |
In Node.js, API requests send User-Agent: worldlabsai-client/<version> node/<version>,
after any userAgent tokens. In browsers the browser's own User-Agent is kept.
An empty key or a rejected key provider stops the request before it is sent.
Retry middleware must clone a request before sending it so its body can be
sent again, and preserve the Idempotency-Key across attempts.
See the Atlas API documentation for API access and usage. JSDoc and TypeScript declarations in the package describe individual methods and options.
License
Copyright 2026 World Labs. Licensed under the Apache License, Version 2.0.
