@apicity/ alibaba (英语)

Alibaba Cloud Model Studio提供商,用于聊天完成,图像生成和流出.

运行时间依赖性 :

• zod@^4.6.6 - 请求在每一个 POST 端点上附加计划 .schema

安装

npm install @apicity/alibaba
# or
pnpm add @apicity/alibaba

快速启动

import { createAlibaba } from "@apicity/alibaba";

const alibaba = createAlibaba({ apiKey: process.env.ALIBABA_API_KEY! });

真实世界的例子:Wan 2.7 图像到视频与同步任务投票

DashScope 软件 aigc/* 家庭是逐一违约的:每个视频、图像和 音频生成端点随即返回 task_id (单位:千美元) task_status 联 合 国 PENDING,而实际的艺术品 生活在一个 单独 GET /api/v1/tasks/{taskId} 民意调查直到过渡到 SUCCEEDED。提供者隐藏 X-DashScope-Async: enable 标题 水管,但保持两叫的形状 因为它让你 检查站 task_id,走开,以后从任何进程恢复. 下面的例子 task_id、时间戳、迅速和解析 从 tests/recordings/alibaba_1329897167/wan-i2v_2196817451/, (中文(简体) ), 这是HAR重播 由 tests/integration/alibaba-wan-i2v.test.ts。 。 。 .

import { readFileSync } from "node:fs";
import { createAlibaba, AlibabaError } from "@apicity/alibaba";
import type {
  AlibabaVideoSynthesisSubmitResponse,
  AlibabaTaskStatusResponse,
  AlibabaTaskStatus,
} from "@apicity/alibaba";

const alibaba = createAlibaba({
  apiKey: process.env.DASHSCOPE_API_KEY!,
  // The SUCCEEDED-path round-trip in the recording is ~47s wall-clock;
  // bump the per-request timeout above the default 30s so the submit
  // call doesn't fight a slow scheduling spike.
  timeout: 60_000,
});

// 1. Inline the source frame as a `data:` URL. DashScope also accepts
//    https:// URLs and `oss://` URIs (the latter only when the request
//    carries `X-DashScope-OssResourceResolve: enable`, which the
//    provider sets automatically on every aigc/* call). Inlining is the
//    zero-infra path — no public bucket, no presigned URL — at the cost
//    of paying the upload bytes once per submit.
const frame = readFileSync("./cat.jpg");
const dataUrl = `data:image/jpeg;base64,${frame.toString("base64")}`;

// 2. `media[].type: "first_frame"` is the I2V kick-off — Wan animates
//    forward from the still. Other media types in the same array slot
//    drive different conditioning modes: `last_frame` (animate
//    backward), `first_clip` (continue a video), `reference` (style
//    transfer). The Zod schema enforces that `first_frame` cannot
//    coexist with `first_clip` and that exactly one of each type is
//    present — invalid combinations fail at `.schema.safeParse(...)`
//    before a single byte hits the wire.
//
// 3. `prompt_extend: true` runs the prompt through DashScope's
//    server-side prompt-enhancement model first, which materially
//    improves motion fidelity on terse prompts like the one below.
//    The enhanced prompt is echoed back in the SUCCEEDED response as
//    `actual_prompt` so you can audit what actually got rendered.
//    `watermark: false` removes the corner badge — silently ignored
//    on tiers that don't permit it.
const submit: AlibabaVideoSynthesisSubmitResponse =
  await alibaba.post.api.v1.services.aigc.videoGeneration.videoSynthesis({
    model: "wan2.7-i2v",
    input: {
      prompt:
        "The odd-eyed white cat blinks slowly, whiskers twitching, " +
        "then turns its head toward the camera",
      media: [{ type: "first_frame", url: dataUrl }],
    },
    parameters: {
      resolution: "720P",
      duration: 5,
      prompt_extend: true,
      watermark: false,
    },
  });

console.log(
  `task=${submit.output.task_id} status=${submit.output.task_status}`,
);
// → "task=5a674d6b-6a42-4b07-98bb-147ba79879ea status=PENDING"

// 4. Poll until terminal. The status state machine is
//    PENDING → RUNNING → (SUCCEEDED | FAILED | CANCELED), with
//    SUSPENDED as a transient quota-bound retry state. Treat anything
//    not in TERMINAL as "keep polling." A 5–10s interval matches the
//    server-side scheduling cadence — the recorded run did 8 polls
//    over ~47s, so faster polling just burns rate-limit budget without
//    moving the task forward.
const TERMINAL: ReadonlyArray<AlibabaTaskStatus> = [
  "SUCCEEDED",
  "FAILED",
  "CANCELED",
];
let status: AlibabaTaskStatusResponse = await alibaba.get.api.v1.tasks(
  submit.output.task_id,
);
while (!TERMINAL.includes(status.output.task_status)) {
  await new Promise((r) => setTimeout(r, 5000));
  status = await alibaba.get.api.v1.tasks(submit.output.task_id);
}

// 5. The task-status response shape *grows* as the task progresses —
//    `submit_time` and `scheduled_time` appear once it leaves PENDING;
//    `end_time`, `orig_prompt`, `video_url`, and `usage` only land on
//    SUCCEEDED. `code` and `message` populate on FAILED. Always branch
//    on `task_status` before reading the success-only fields, since
//    they're typed `string | undefined`.
if (status.output.task_status !== "SUCCEEDED") {
  throw new AlibabaError(
    `i2v task ${status.output.task_id} ${status.output.task_status}: ` +
      `${status.output.code ?? "?"}: ${status.output.message ?? "?"}`,
    500,
    status.output,
    status.output.code,
  );
}

console.log(status.output.video_url);
// → "https://dashscope-a717.oss-accelerate.aliyuncs.com/.../70873660-metadata_user_a54afaea6b53dd4e.mp4?Expires=1776489167&..."

const elapsed =
  new Date(status.output.end_time!).getTime() -
  new Date(status.output.submit_time!).getTime();
console.log(
  `model=wan2.7-i2v ${status.usage!.SR}p×${status.usage!.output_video_duration}s ` +
    `elapsed=${(elapsed / 1000).toFixed(1)}s videos=${status.usage!.video_count}`,
);
// → "model=wan2.7-i2v 720p×5s elapsed=47.4s videos=1"

页:1

• 回来的 video_url 是带有短句的预先签名的OSS URL Expires= 窗口(以上录入的qq1小时)——下载或 立即重新主持,不要存储URL本身. 这桶是 托管时间 oss-accelerate.aliyuncs.com捍卫阿里巴巴CDN a. 与调用器相近 获取.
• 提交电话是 廉价 即使后来的任务是开帐单 仅按任务收取 usage.duration (单位:秒) 输出视频)。 内容安全屏幕失败( A)code: "DataInspectionFailed")在输入框上返回一个SUCCEED-形状 HTTP 200 带 task_status: "FAILED"而不是4xx,这就是为什么 上面的例子总是读取 task_status 而不是依赖 内容相关拒绝的例外流程.
• 一样 videoSynthesis 端点遍布整个湾 2.7 通过改变家庭 model数字 : wan2.7-i2v 为图像-视频, wan2.7-t2v 文本-视频(删除 media 阵列),以及 wan2.7-videoedit 用于视频式传输(使用) media[].type: "video") (中文(简体) ). Zod计划执行每型媒体型 组合- videoedit 需要一个 video 条目, i2v 需求 first_frame 或者说 first_clip等 (中文(简体) ).
• 对于输入框架超过DashScope 10MB的有效载荷 嵌入式数据- URL 天花板, 互换内线 data: 一个 URL oss://{key} 通过 uploadFile(provider, {...}) - 那个 导出助手执行 getPolicy + 多部分开放源码软件后台对象 跳起舞来返回URI 准备跳入 media[].url编辑 X-DashScope-OssResourceResolve 自动设置页眉 每个aigc/* 调用所以 URI 解决服务器侧.
• 丢出错误 AlibabaError 与 status 和解析 body编辑 本地aigc 错误形状( r){code, message, request_id}已浮出水面 内 error.code - 与 withRetry 从 @apicity/alibaba 页:1 429 编号 : 503但跳过重试 code === "DataInspectionFailed" 编号 : "InvalidParameter" 因为这些是决定性的拒绝.

API 参考

7个端点跨出4组. 每个方法都映射出上游的 URL 路径 .

兼容模式

const res = await alibaba.get.compatibleMode.v1.models();

const res = await alibaba.post.compatibleMode.v1.chat.completions({ /* ... */ });

服务

const res = await alibaba.post.api.v1.services.aigc.imageGeneration.generation({ /* ... */ });

const res = await alibaba.post.api.v1.services.aigc.multimodalGeneration.generation({ /* ... */ });

const res = await alibaba.post.api.v1.services.aigc.videoGeneration.videoSynthesis({ /* ... */ });

任务

const res = await alibaba.get.api.v1.tasks({ /* ... */ });

上传

const res = await alibaba.get.api.v1.uploads({ /* ... */ });

中间软件

import { createAlibaba, withRetry } from "@apicity/alibaba";

const alibaba = createAlibaba({ apiKey: process.env.ALIBABA_API_KEY! });
const getTask = withRetry(alibaba.get.api.v1.tasks, { retries: 3 });

部分 辣点 单相机.

许可证

麻省理工学院——见 自由主义。 。 。 .