Cookie Preferences
We use cookies to personalize content and analyze traffic. See our Cookie Policy.
Apipass SDK（@apipass-dev/apipass-sdk）是面向 ApiPass API 的 TypeScript 客户端。推荐通过 client.jobs 创建任务并查询结果——这是覆盖所有模型的统一入口。SDK 还提供类型化封装、对话补全、资源上传等辅助能力。
请先确认你已经准备好：
在项目中安装包：
1npm install @apipass-dev/apipass-sdk或使用 Yarn：
1yarn add @apipass-dev/apipass-sdk导入 Apipass 并显式传入 API Key：
1import { Apipass } from "@apipass-dev/apipass-sdk";
2
3const apiKey = process.env.APIPASS_API_KEY;
4if (!apiKey) {
5 throw new Error("创建 Apipass 客户端前请先设置 APIPASS_API_KEY。");
6}
7
8const client = new Apipass({
9 apiKey,
10});可按需覆盖默认值：
1const client = new Apipass({
2 apiKey: process.env.APIPASS_API_KEY!,
3 baseURL: "https://api.apipass.dev/api/v1",
4 timeout: 60_000,
5});| 选项 | 默认值 | 说明 |
|---|---|---|
apiKey | — | 必填。你的 ApiPass API Key。 |
baseURL | https://api.apipass.dev/api/v1 | Jobs 与 Chat 请求的基础 URL。 |
timeout | 60000 | 请求超时（毫秒）。 |
环境变量 APIPASS_BASE_URL 也可用于覆盖 API 基础 URL。
ApiPass 上绝大多数模型（图像、视频、音乐等）都走异步任务流程：创建任务 → 获取 taskId → 轮询或等待回调 → 读取结果。推荐统一使用 client.jobs：
1import { Apipass, Models } from "@apipass-dev/apipass-sdk";
2
3const client = new Apipass({ apiKey: process.env.APIPASS_API_KEY! });
4
5// 1. 创建任务
6const task = await client.jobs.createTask({
7 model: Models.NanoBanana2,
8 input: {
9 prompt: "宁静的高山湖泊",
10 aspect_ratio: "16:9",
11 resolution: "1K",
12 },
13});
14
15console.log("Task ID:", task.data.taskId);
16
17// 2. 查询结果
18const status = await client.jobs.recordInfo(task.data.taskId);
19
20if (status.data.state === "success") {
21 console.log(status.data.result?.resultUrls);
22}createTask 接受任意 ApiPass 模型名称，input 字段与 REST API 一致。对于 SDK 已知的模型 ID，TypeScript 会根据 model 值自动提示对应的 input 字段。
可选字段 channel 控制路由策略：
| 值 | 说明 |
|---|---|
"auto" | 默认依次尝试 starter，有资格时尝试 enterprise，然后是 regular，最后是 official。 |
"starter" | 超低成本通道。 |
"enterprise" | 企业价格。 |
"regular" | 标准低成本通道。 |
"official" | 模型官方原生 API 提供商。 |
1await client.jobs.createTask({
2 model: "google/nano-banana-2",
3 channel: "official",
4 input: { prompt: "宁静的高山湖泊" },
5});创建任务时传入 callBackUrl，任务完成后 ApiPass 会向你的端点发送 Webhook，无需持续轮询：
1await client.jobs.createTask({
2 model: Models.NanoBanana2,
3 input: {
4 prompt: "干净背景上的产品照片",
5 resolution: "2K",
6 },
7 callBackUrl: "https://your-domain.com/api/callback",
8});导入 Models 以获得 IDE 自动补全，避免手写模型 ID：
1import { Models } from "@apipass-dev/apipass-sdk";
2
3await client.jobs.createTask({
4 model: Models.Kling26,
5 input: {
6 prompt: "日落时分，巨龙飞越中世纪城堡",
7 duration: 5,
8 aspect_ratio: "16:9",
9 generate_audio: true,
10 },
11});Models 涵盖图像、视频、音频、对话等 SDK 已知模型 ID。未知模型 ID 同样可用，只是 input 不会获得类型提示：
1await client.jobs.createTask({
2 model: "provider/new-model",
3 input: {
4 provider_specific_param: true,
5 },
6});部分热门模型在 client.images、client.videos、client.audio 下提供了类型化封装。底层仍调用 Jobs API，但会将 camelCase 字段映射为 API 载荷，并在发送前校验常见输入约束。若你偏好更简洁的调用方式，可以使用这些封装：
1// 创建任务
2const task = await client.images.nanoBanana2.create({
3 prompt: "日落时分，宁静的高山湖泊倒映着雪峰",
4 aspectRatio: "16:9",
5 resolution: "1K",
6 outputFormat: "jpg",
7});
8
9// 查询结果
10const result = await client.images.nanoBanana2.retrieve(task.data.taskId);
11
12if (result.data.state === "success") {
13 console.log(result.data.result?.resultUrls);
14}| 命名空间 | 示例 |
|---|---|
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（含 extend、cover、lyrics、vocalSeparation 等） |
对话类模型不走 Jobs 流程，而是通过 client.chat.completions.create 同步返回结果（也支持流式）：
1const completion = await client.chat.completions.create({
2 model: "apipass-chat",
3 messages: [
4 { role: "system", content: "回答要简洁。" },
5 { role: "user", content: "用一句话解释 embedding。" },
6 ],
7 temperature: 0.3,
8});
9
10console.log(completion.choices[0]?.message.content);已知对话模型可通过 Models 引用：
1await client.chat.completions.create({
2 model: Models.Gemini3FlashPreview,
3 messages: [{ role: "user", content: "你好" }],
4});
5
6await client.chat.completions.create({
7 model: Models.Gemini3ProPreview,
8 messages: [{ role: "user", content: "分析这个架构。" }],
9 temperature: 0.7,
10 max_tokens: 8192,
11});
12
13await client.chat.completions.create({
14 model: Models.Gpt55,
15 messages: [{ role: "user", content: "用三条要点总结以下内容。" }],
16 temperature: 0.7,
17 max_tokens: 512,
18});Gemini 模型支持多模态输入：
1await client.chat.completions.create({
2 model: Models.Gemini3FlashPreview,
3 messages: [
4 {
5 role: "user",
6 content: [
7 { type: "text", text: "描述这张图片" },
8 {
9 type: "image_url",
10 image_url: { url: "https://example.com/image.jpg" },
11 },
12 ],
13 },
14 ],
15});流式输出：
1const stream = await client.chat.completions.create({
2 model: "apipass-chat",
3 messages: [{ role: "user", content: "从一数到五。" }],
4 stream: true,
5});
6
7for await (const chunk of stream) {
8 process.stdout.write(chunk.choices[0]?.delta.content ?? "");
9}创建任务前，若需要将本地文件作为模型输入，可先上传到 ApiPass 托管存储获取公开 URL：
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.txt同样的方法也可通过 resource 命名空间调用：
1const image = await client.resources.upload({
2 file: imageBlob,
3 folder: "images",
4});SDK 会请求预签名上传 URL，将文件上传到 Cloudflare，并返回公开 CDN 地址。若省略 fileName，会在 folder 下生成唯一对象键。上传完成后，将返回的 URL 填入 createTask 的 input 字段即可。
不确定该用哪个模型或需要哪些 input 字段时，可以查询在线目录：
1const onlineModels = await client.models();
2console.log(onlineModels.map((model) => model.name));获取某个模型的 Playground 输入字段：
1const fields = await client.info(Models.NanoBanana2);
2console.log(fields);SDK 导出以下类型化错误类：
1import {
2 ApipassError,
3 ApipassAPIError,
4 ApipassConfigurationError,
5 ApipassResponseError,
6} from "@apipass-dev/apipass-sdk";ApipassConfigurationError — 客户端配置缺失或无效（例如未传 API Key）。ApipassResponseError — 非 2xx HTTP 响应，包含状态码与响应体详情。ApipassAPIError — 响应 envelope 中的 API 级错误。1import { Apipass, Models } from "@apipass-dev/apipass-sdk";
2
3const client = new Apipass({ apiKey: process.env.APIPASS_API_KEY! });
4
5// 创建任务（推荐）
6await client.jobs.createTask({ model: Models.NanoBanana2, input: { prompt: "..." } });
7await client.jobs.recordInfo(taskId);
8
9// 类型化封装
10await client.images.nanoBanana2.create({ prompt: "..." });
11await client.images.nanoBanana2.retrieve(taskId);
12
13// 对话（同步 / 流式）
14await client.chat.completions.create({ model: "apipass-chat", messages: [...] });
15await client.chat.completions.create({ model: "apipass-chat", messages: [...], stream: true });
16
17// 上传
18await client.uploadResource({ file, folder: "images" });
19
20// 目录
21await client.models();
22await client.info(Models.NanoBanana2);各模型的具体参数与 REST API 细节，请参阅 ApiPass 市场中对应模型页面的文档。