SDK quickstart

@ai-dubbing/sdk is generated from the /v1 API contract. It provides typed functions for Studio and third-party integrations and uses the Fetch API.

Install

Inside this monorepo, add the workspace package to your application:

{
  "dependencies": {
    "@ai-dubbing/sdk": "workspace:*"
  }
}

Then install workspace dependencies:

bun install

The package is currently an internal workspace package. Publish it to your package registry before consuming it from a separate repository.

Configure the SDK

Configure the exported singleton once during application startup. Use your deployed API origin without a trailing slash.

import { client } from "@ai-dubbing/sdk";

client.setConfig({
  baseUrl: "https://api.example.com",
  headers: {
    "x-api-key": process.env.AI_DUBBING_API_KEY!,
  },
});

For server integrations, use an organization API key and keep it in a server-side environment variable. Studio uses the same SDK with its authenticated cookie session; never configure an API key in browser code.

Make a request

SDK functions return { data, response } by default. Set throwOnError: true to make non-2xx responses throw instead of returning an error result.

import { listDubs } from "@ai-dubbing/sdk";

const { data: jobs } = await listDubs({
  throwOnError: true,
});

for (const job of jobs) {
  console.log(job.id, job.status, job.progress);
}

Handle API errors

The API error payload is JSON shaped like { error: string }. When using throwOnError, normalize errors before showing them to a user or logging them.

function apiErrorMessage(error: unknown) {
  if (error instanceof Error) return error.message;
  if (error && typeof error === "object" && "error" in error) {
    const message = (error as { error?: unknown }).error;
    if (typeof message === "string") return message;
  }
  return "Request failed";
}