Cookie Preferences
We use cookies to personalize content and analyze traffic. See our Cookie Policy.
The Apipass SDK (@apipass-dev/apipass-sdk) is a TypeScript-first client for calling ApiPass APIs. The recommended integration path is client.jobs — create a task, then poll or wait for a callback. The SDK also provides typed helpers, chat completions, resource uploads, and other convenience APIs.
Make sure you have:
Install the package in your project:
1npm install @apipass-dev/apipass-sdkOr with Yarn:
1yarn add @apipass-dev/apipass-sdkImport Apipass and pass your API key explicitly:
1import { Apipass } from "@apipass-dev/apipass-sdk";
2
3const apiKey = process.env.APIPASS_API_KEY;
4if (!apiKey) {
5 throw new Error("Set APIPASS_API_KEY before creating the Apipass client.");
6}
7
8const client = new Apipass({
9 apiKey,
10});You can override defaults when needed:
1const client = new Apipass({
2 apiKey: process.env.APIPASS_API_KEY!,
3 baseURL: "https://api.apipass.dev/api/v1",
4 timeout: 60_000,
5});| Option | Default | Description |
|---|---|---|
apiKey | — | Required. Your ApiPass API key. |
baseURL | https://api.apipass.dev/api/v1 | Base URL for jobs and chat requests. |
timeout | 60000 | Request timeout in milliseconds. |
APIPASS_BASE_URL is also supported as an environment override for the API base URL.
Most models on ApiPass (image, video, music, and more) run as asynchronous tasks: create a task → get a taskId → poll or wait for a callback → read the result. Use client.jobs as the unified entry point:
1import { Apipass, Models } from "@apipass-dev/apipass-sdk";
2
3const client = new Apipass({ apiKey: process.env.APIPASS_API_KEY! });
4
5// 1. Create a task
6const task = await client.jobs.createTask({
7 model: Models.NanoBanana2,
8 input: {
9 prompt: "A serene alpine lake",
10 aspect_ratio: "16:9",
11 resolution: "1K",
12 },
13});
14
15console.log("Task ID:", task.data.taskId);
16
17// 2. Poll for results
18const status = await client.jobs.recordInfo(task.data.taskId);
19
20if (status.data.state === "success") {
21 console.log(status.data.result?.resultUrls);
22}createTask accepts any ApiPass model name, and input matches the REST API payload. For SDK-known model IDs, TypeScript suggests the documented input fields based on the model value.
The optional channel field controls routing:
| Value | Description |
|---|---|
"auto" | Default. Try starter, then eligible-user enterprise, then regular, then official. |
"starter" | Ultra-low-cost tier. |
"enterprise" | Enterprise pricing. |
"regular" | Standard lower-cost tier. |
"official" | Native official API provider. |
1await client.jobs.createTask({
2 model: "google/nano-banana-2",
3 channel: "official",
4 input: { prompt: "A serene alpine lake" },
5});Pass callBackUrl when creating a task to receive a webhook when it finishes, instead of polling:
1await client.jobs.createTask({
2 model: Models.NanoBanana2,
3 input: {
4 prompt: "A product photo on a clean studio background",
5 resolution: "2K",
6 },
7 callBackUrl: "https://your-domain.com/api/callback",
8});Import Models for autocomplete-friendly model IDs:
1import { Models } from "@apipass-dev/apipass-sdk";
2
3await client.jobs.createTask({
4 model: Models.Kling26,
5 input: {
6 prompt: "A majestic dragon flying over a medieval castle at sunset",
7 duration: 5,
8 aspect_ratio: "16:9",
9 generate_audio: true,
10 },
11});Models covers known SDK model IDs across image, video, audio, and chat APIs. Unknown model IDs still work — you just won't get typed input hints:
1await client.jobs.createTask({
2 model: "provider/new-model",
3 input: {
4 provider_specific_param: true,
5 },
6});Popular models also have typed helpers under client.images, client.videos, and client.audio. These still call the Jobs API under the hood, but map camelCase fields to the API payload and validate common input constraints. Use them if you prefer a more concise call style:
1// Create a task
2const task = await client.images.nanoBanana2.create({
3 prompt: "A serene alpine lake reflecting snow-capped mountains at golden hour",
4 aspectRatio: "16:9",
5 resolution: "1K",
6 outputFormat: "jpg",
7});
8
9// Poll for results
10const result = await client.images.nanoBanana2.retrieve(task.data.taskId);
11
12if (result.data.state === "success") {
13 console.log(result.data.result?.resultUrls);
14}| Namespace | Examples |
|---|---|
client.images | nanoBanana2, nanoBananaPro, gptImage2, fluxProImage2, qwenImage2, seedream5LiteImage, wan27Image, wan27ImagePro, imageFaceSwap, imageWatermakerRemove |
client.videos | veo31Fast, veo31Lite, veo31Quality, kling26, klingV3Video, hailuo23, seedance2, omniHuman15, klingAvatarV2, kling26MotionControl, wan26VideoToVideo |
client.audio | music15, textToDialogueV3, suno (with extend, cover, lyrics, vocalSeparation, etc.) |
Chat models do not use the Jobs flow. They return results synchronously through client.chat.completions.create (streaming is also supported):
1const completion = await client.chat.completions.create({
2 model: "apipass-chat",
3 messages: [
4 { role: "system", content: "You are concise." },
5 { role: "user", content: "Explain embeddings in one sentence." },
6 ],
7 temperature: 0.3,
8});
9
10console.log(completion.choices[0]?.message.content);Known chat models are available through Models:
1await client.chat.completions.create({
2 model: Models.Gemini3FlashPreview,
3 messages: [{ role: "user", content: "Hello" }],
4});
5
6await client.chat.completions.create({
7 model: Models.Gemini3ProPreview,
8 messages: [{ role: "user", content: "Analyze this architecture." }],
9 temperature: 0.7,
10 max_tokens: 8192,
11});
12
13await client.chat.completions.create({
14 model: Models.Gpt55,
15 messages: [{ role: "user", content: "Summarize this in three bullets." }],
16 temperature: 0.7,
17 max_tokens: 512,
18});Gemini models also support multimodal input:
1await client.chat.completions.create({
2 model: Models.Gemini3FlashPreview,
3 messages: [
4 {
5 role: "user",
6 content: [
7 { type: "text", text: "Describe this image" },
8 {
9 type: "image_url",
10 image_url: { url: "https://example.com/image.jpg" },
11 },
12 ],
13 },
14 ],
15});Streaming:
1const stream = await client.chat.completions.create({
2 model: "apipass-chat",
3 messages: [{ role: "user", content: "Count to five." }],
4 stream: true,
5});
6
7for await (const chunk of stream) {
8 process.stdout.write(chunk.choices[0]?.delta.content ?? "");
9}Before creating a task, upload local files to ApiPass-managed storage to get public URLs for model inputs:
1const file = new Blob(["hello"], { type: "text/plain" });
2
3const resource = await client.uploadResource({
4 file,
5 fileName: "resources/hello.txt",
6});
7
8console.log(resource.url);
9// https://cdn.apipass.dev/resources/hello.txtThe same method is available under the resource namespace:
1const image = await client.resources.upload({
2 file: imageBlob,
3 folder: "images",
4});The SDK requests a presigned upload URL, uploads to Cloudflare, and returns the public CDN URL. If fileName is omitted, it generates a unique key under folder. Pass the returned URL into your createTask input fields.
When you're unsure which model to use or what input fields are required:
1const onlineModels = await client.models();
2console.log(onlineModels.map((model) => model.name));Fetch playground input fields for a specific model:
1const fields = await client.info(Models.NanoBanana2);
2console.log(fields);The SDK exports typed error classes:
1import {
2 ApipassError,
3 ApipassAPIError,
4 ApipassConfigurationError,
5 ApipassResponseError,
6} from "@apipass-dev/apipass-sdk";ApipassConfigurationError — missing or invalid client configuration (e.g. no API key).ApipassResponseError — non-2xx HTTP responses with status and body details.ApipassAPIError — API-level errors returned in the response envelope.1import { Apipass, Models } from "@apipass-dev/apipass-sdk";
2
3const client = new Apipass({ apiKey: process.env.APIPASS_API_KEY! });
4
5// Create a task (recommended)
6await client.jobs.createTask({ model: Models.NanoBanana2, input: { prompt: "..." } });
7await client.jobs.recordInfo(taskId);
8
9// Typed helpers
10await client.images.nanoBanana2.create({ prompt: "..." });
11await client.images.nanoBanana2.retrieve(taskId);
12
13// Chat (sync / stream)
14await client.chat.completions.create({ model: "apipass-chat", messages: [...] });
15await client.chat.completions.create({ model: "apipass-chat", messages: [...], stream: true });
16
17// Upload
18await client.uploadResource({ file, folder: "images" });
19
20// Catalog
21await client.models();
22await client.info(Models.NanoBanana2);For model-specific parameters and REST API details, see the corresponding model pages in the ApiPass marketplace documentation.