@volcengine/ark-runtime 1.0.0

package/example/list-input-items.ts

@@ -0,0 +1,34 @@
+/**
+ * Response Input Items 分页列表示例
+ * 对齐 Go SDK: example/listinputitems/main.go
+ */
+import { ArkRuntimeClient } from "@volcengine/ark-runtime";
+
+const client = ArkRuntimeClient.withApiKey(process.env.ARK_API_KEY!);
+const MODEL = "doubao-seed-2-0-pro-260215";
+
+async function listInputItems() {
+  // 先创建一个 Response
+  console.log("----- 创建 Response -----");
+  const response = await client.createResponses({
+    model: MODEL,
+    input: "Hello world",
+  });
+  console.log("Response ID:", response.id);
+
+  // 列出该 Response 的 input items
+  console.log("\n----- List Input Items -----");
+  const items = await client.listResponseInputItems(response.id as string);
+  console.log("Input Items:", JSON.stringify(items, null, 2));
+
+  // 删除 Response
+  console.log("\n----- 删除 Response -----");
+  await client.deleteResponse(response.id as string);
+  console.log("Deleted.");
+}
+
+async function main() {
+  await listInputItems();
+}
+
+main().catch(console.error);

package/example/multimodal-embeddings.ts

@@ -0,0 +1,36 @@
+/**
+ * 多模态 Embedding 示例
+ * 对齐 Go SDK: example/multimodalembeddings/main.go
+ */
+import { ArkRuntimeClient } from "@volcengine/ark-runtime";
+
+const client = ArkRuntimeClient.withApiKey(process.env.ARK_API_KEY!);
+const MODEL = process.env.ARK_MULTIMODAL_EMBEDDING_MODEL ?? "doubao-embedding-vision";
+
+async function multimodalEmbedding() {
+  console.log("----- 多模态 Embedding -----");
+
+  const response = await client.createMultiModalEmbeddings({
+    model: MODEL,
+    input: [
+      {
+        type: "image_url",
+        image_url: {
+          url: "https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png",
+        },
+      },
+      {
+        type: "text",
+        text: "一个彩色的logo",
+      },
+    ],
+  });
+
+  console.log("Response:", JSON.stringify(response, null, 2));
+}
+
+async function main() {
+  await multimodalEmbedding();
+}
+
+main().catch(console.error);

package/example/responses/basic.ts

@@ -0,0 +1,75 @@
+/**
+ * Responses API 基础示例
+ * 对齐 Go SDK: example/responses/basic/main.go
+ */
+import { ArkRuntimeClient } from "@volcengine/ark-runtime";
+
+const client = ArkRuntimeClient.withApiKey(process.env.ARK_API_KEY!);
+const MODEL = "doubao-seed-2-0-pro-260215";
+
+async function basicResponse() {
+  console.log("----- Responses API (非流式) -----");
+
+  const response = await client.createResponses({
+    model: MODEL,
+    input: "解释什么是量子计算",
+  });
+
+  console.log("Response ID:", response.id);
+  console.log("Status:", response.status);
+  console.log("Output:", JSON.stringify(response.output, null, 2));
+}
+
+async function responseWithImageInput() {
+  console.log("\n----- Responses API (图片输入) -----");
+
+  const response = await client.createResponses({
+    model: MODEL,
+    input: [
+      {
+        role: "user",
+        content: [
+          { type: "input_text", text: "这张图片是什么？" },
+          {
+            type: "input_image",
+            image_url: "https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png",
+          },
+        ],
+      } as any,
+    ],
+  });
+
+  console.log("Response:", JSON.stringify(response, null, 2));
+}
+
+async function multiTurnResponse() {
+  console.log("\n----- Responses API (多轮对话) -----");
+
+  // 第一轮
+  const resp1 = await client.createResponses({
+    model: MODEL,
+    input: "记住数字42",
+  });
+  console.log("Turn 1 ID:", resp1.id);
+
+  // 第二轮：引用前一轮
+  const resp2 = await client.createResponses({
+    model: MODEL,
+    input: [
+      { type: "response", id: resp1.id } as any,
+      {
+        role: "user",
+        content: [{ type: "input_text", text: "我刚才让你记住的数字是什么？" }],
+      } as any,
+    ],
+  });
+  console.log("Turn 2 Output:", JSON.stringify(resp2.output, null, 2));
+}
+
+async function main() {
+  await basicResponse();
+  await responseWithImageInput();
+  await multiTurnResponse();
+}
+
+main().catch(console.error);

package/example/responses/doubao-app.ts

@@ -0,0 +1,53 @@
+/**
+ * Responses API Doubao App 功能示例
+ * 对齐 Go SDK: example/responses/doubao_app/main.go
+ *
+ * 支持 Doubao 平台特定功能：chat, deepChat, aiSearch, reasoningSearch
+ */
+import { ArkRuntimeClient } from "@volcengine/ark-runtime";
+import { getEventType, isDelta, isResponseDone } from "@volcengine/ark-runtime";
+
+const client = ArkRuntimeClient.withApiKey(process.env.ARK_API_KEY!);
+const MODEL = "doubao-seed-2-0-pro-260215";
+
+async function doubaoFeatureChat(featureType: string) {
+  console.log(`\n----- Doubao Feature: ${featureType} -----`);
+
+  const stream = await client.createResponsesStream({
+    model: MODEL,
+    input: [
+      {
+        role: "user",
+        content: [{ type: "input_text", text: "解释什么是人工智能" }],
+      } as any,
+    ],
+    tools: [
+      {
+        type: "doubao_feature",
+        doubao_feature: { type: featureType },
+      },
+    ],
+  } as any);
+
+  for await (const event of stream) {
+    if (isDelta(event)) {
+      const delta = event as any;
+      if (delta.delta) {
+        process.stdout.write(delta.delta);
+      }
+    }
+    if (isResponseDone(event)) {
+      console.log(`\n[Done] ${getEventType(event)}`);
+    }
+  }
+}
+
+async function main() {
+  // 测试不同的 Doubao 功能类型
+  await doubaoFeatureChat("chat");
+  await doubaoFeatureChat("deepChat");
+  await doubaoFeatureChat("aiSearch");
+  await doubaoFeatureChat("reasoningSearch");
+}
+
+main().catch(console.error);

package/example/responses/mcp.ts

@@ -0,0 +1,66 @@
+/**
+ * Responses API MCP (Model Context Protocol) 工具示例
+ * 对齐 Go SDK: example/responses/mcp/main.go
+ */
+import { ArkRuntimeClient } from "@volcengine/ark-runtime";
+import { getEventType } from "@volcengine/ark-runtime";
+
+const client = ArkRuntimeClient.withApiKey(process.env.ARK_API_KEY!);
+const MODEL = "doubao-seed-2-0-pro-260215";
+
+async function mcpNonStream() {
+  console.log("----- MCP Tool (非流式) -----");
+
+  const response = await client.createResponses({
+    model: MODEL,
+    input: "查询今天北京的天气",
+    tools: [
+      {
+        type: "mcp",
+        server_label: "weather",
+        server_url: "https://example.com/mcp/weather",
+        require_approval: "never",
+      },
+    ],
+  } as any);
+
+  console.log("Response:", JSON.stringify(response, null, 2));
+}
+
+async function mcpStream() {
+  console.log("\n----- MCP Tool (流式) -----");
+
+  const stream = await client.createResponsesStream({
+    model: MODEL,
+    input: "查询上海的天气",
+    tools: [
+      {
+        type: "mcp",
+        server_label: "weather",
+        server_url: "https://example.com/mcp/weather",
+        require_approval: "never",
+      },
+    ],
+  } as any);
+
+  for await (const event of stream) {
+    const eventType = getEventType(event);
+
+    if (eventType.includes("mcp")) {
+      console.log(`[MCP] ${eventType}`, JSON.stringify(event, null, 2));
+    }
+
+    const delta = event as any;
+    if (delta.delta && typeof delta.delta === "string") {
+      process.stdout.write(delta.delta);
+    }
+  }
+  console.log();
+}
+
+async function main() {
+  await mcpNonStream();
+  await mcpStream();
+}
+
+main().catch(console.error);

package/example/responses/streaming.ts

@@ -0,0 +1,45 @@
+/**
+ * Responses API 流式示例
+ * 对齐 Go SDK: example/responses/web_search/main.go (streaming 部分)
+ */
+import { ArkRuntimeClient } from "@volcengine/ark-runtime";
+import {
+  getEventType,
+  isDelta,
+  isDeltaDone,
+  isResponseDone,
+} from "@volcengine/ark-runtime";
+
+const client = ArkRuntimeClient.withApiKey(process.env.ARK_API_KEY!);
+const MODEL = "doubao-seed-2-0-pro-260215";
+
+async function responsesStream() {
+  console.log("----- Responses API 流式 -----");
+
+  const stream = await client.createResponsesStream({
+    model: MODEL,
+    input: "写一首关于春天的诗",
+  });
+
+  for await (const event of stream) {
+    const eventType = getEventType(event);
+
+    if (isDelta(event)) {
+      // 增量文本
+      const delta = event as any;
+      if (delta.delta) {
+        process.stdout.write(delta.delta);
+      }
+    } else if (isDeltaDone(event)) {
+      console.log(`\n[Delta Done] type=${eventType}`);
+    } else if (isResponseDone(event)) {
+      console.log(`[Response Done] type=${eventType}`);
+    }
+  }
+}
+
+async function main() {
+  await responsesStream();
+}
+
+main().catch(console.error);

package/example/responses/video.ts

@@ -0,0 +1,74 @@
+/**
+ * Responses API 视频理解示例
+ * 对齐 Go SDK: example/responses/video/main.go
+ *
+ * 支持 file:// URL 自动上传：SDK 会自动上传本地文件并替换为 file_id
+ */
+import { ArkRuntimeClient } from "@volcengine/ark-runtime";
+import { getEventType, isDelta } from "@volcengine/ark-runtime";
+
+const client = ArkRuntimeClient.withApiKey(process.env.ARK_API_KEY!);
+const MODEL = "doubao-seed-2-0-pro-260215";
+
+async function videoUnderstanding() {
+  console.log("----- 视频理解 (Responses API) -----");
+
+  // 使用远程视频 URL
+  const response = await client.createResponses({
+    model: MODEL,
+    input: [
+      {
+        role: "user",
+        content: [
+          { type: "input_text", text: "描述这个视频的内容" },
+          {
+            type: "input_video",
+            video_url: "https://example.com/sample-video.mp4",
+          },
+        ],
+      } as any,
+    ],
+  });
+
+  console.log("Response:", JSON.stringify(response, null, 2));
+}
+
+async function videoUnderstandingLocalFile() {
+  console.log("\n----- 视频理解 (本地文件自动上传) -----");
+
+  // 使用 file:// URL，SDK 会自动上传并替换为 file_id
+  const stream = await client.createResponsesStream({
+    model: MODEL,
+    input: [
+      {
+        role: "user",
+        content: [
+          { type: "input_text", text: "这个视频讲了什么？" },
+          {
+            type: "input_video",
+            // file:// URL 会被 SDK 自动上传
+            video_url: "file:///path/to/local/video.mp4",
+          },
+        ],
+      } as any,
+    ],
+  });
+
+  for await (const event of stream) {
+    if (isDelta(event)) {
+      const delta = event as any;
+      if (delta.delta) {
+        process.stdout.write(delta.delta);
+      }
+    }
+  }
+  console.log();
+}
+
+async function main() {
+  await videoUnderstanding();
+  // 取消注释下面一行来测试本地文件上传
+  // await videoUnderstandingLocalFile();
+}
+
+main().catch(console.error);

package/example/responses/web-search.ts

@@ -0,0 +1,52 @@
+/**
+ * Responses API Web Search 示例
+ * 对齐 Go SDK: example/responses/web_search/main.go
+ */
+import { ArkRuntimeClient } from "@volcengine/ark-runtime";
+import { getEventType } from "@volcengine/ark-runtime";
+
+const client = ArkRuntimeClient.withApiKey(process.env.ARK_API_KEY!);
+const MODEL = "doubao-seed-2-0-pro-260215";
+
+async function webSearchNonStream() {
+  console.log("----- Web Search (非流式) -----");
+
+  const response = await client.createResponses({
+    model: MODEL,
+    input: "2024年诺贝尔物理学奖获得者是谁？",
+    tools: [{ type: "web_search_call" }],
+  } as any);
+
+  console.log("Response:", JSON.stringify(response, null, 2));
+}
+
+async function webSearchStream() {
+  console.log("\n----- Web Search (流式) -----");
+
+  const stream = await client.createResponsesStream({
+    model: MODEL,
+    input: "今天的最新科技新闻是什么？",
+    tools: [{ type: "web_search_call" }],
+  } as any);
+
+  for await (const event of stream) {
+    const eventType = getEventType(event);
+
+    if (eventType.includes("web_search")) {
+      console.log(`[WebSearch] ${eventType}`);
+    }
+
+    const delta = event as any;
+    if (delta.delta && typeof delta.delta === "string") {
+      process.stdout.write(delta.delta);
+    }
+  }
+  console.log();
+}
+
+async function main() {
+  await webSearchNonStream();
+  await webSearchStream();
+}
+
+main().catch(console.error);

package/example/structured-outputs.ts

@@ -0,0 +1,71 @@
+/**
+ * 结构化输出示例 (JSON Schema Response Format)
+ * 对齐 Go SDK: example/structured_outputs/main.go
+ */
+import { ArkRuntimeClient } from "@volcengine/ark-runtime";
+
+const client = ArkRuntimeClient.withApiKey(process.env.ARK_API_KEY!);
+const MODEL = "doubao-seed-2-0-pro-260215";
+
+// 定义期望输出的 JSON Schema
+const personSchema = {
+  type: "object",
+  properties: {
+    name: { type: "string", description: "人物名称" },
+    age: { type: "integer", description: "年龄" },
+    occupation: { type: "string", description: "职业" },
+    hobbies: {
+      type: "array",
+      items: { type: "string" },
+      description: "爱好列表",
+    },
+  },
+  required: ["name", "age", "occupation", "hobbies"],
+};
+
+async function structuredOutput() {
+  console.log("----- 结构化输出 -----");
+
+  const response = await client.createChatCompletion({
+    model: MODEL,
+    messages: [
+      {
+        role: "user",
+        content: "请生成一个虚构人物的信息，包含姓名、年龄、职业和爱好。",
+      },
+    ],
+    response_format: {
+      type: "json_schema",
+      json_schema: {
+        name: "person_info",
+        description: "人物信息",
+        schema: personSchema,
+        strict: true,
+      },
+    },
+  });
+
+  const content = response.choices[0].message.content;
+  console.log("Raw response:", content);
+
+  // 解析为类型化对象
+  if (typeof content === "string") {
+    const person = JSON.parse(content) as {
+      name: string;
+      age: number;
+      occupation: string;
+      hobbies: string[];
+    };
+    console.log("Parsed person:", person);
+    console.log("  Name:", person.name);
+    console.log("  Age:", person.age);
+    console.log("  Occupation:", person.occupation);
+    console.log("  Hobbies:", person.hobbies.join(", "));
+  }
+}
+
+async function main() {
+  await structuredOutput();
+}
+
+main().catch(console.error);

package/example/tokenization.ts

@@ -0,0 +1,30 @@
+/**
+ * Tokenization（分词计数）示例
+ * 对齐 Go SDK: example/tokenization/main.go
+ */
+import { ArkRuntimeClient } from "@volcengine/ark-runtime";
+
+const client = ArkRuntimeClient.withApiKey(process.env.ARK_API_KEY!);
+const MODEL = "doubao-seed-2-0-pro-260215";
+
+async function tokenize() {
+  console.log("----- Tokenization -----");
+
+  const response = await client.createTokenization({
+    model: MODEL,
+    text: "hello world, 你好世界！",
+  });
+
+  console.log("Response:", JSON.stringify(response, null, 2));
+
+  for (const item of response.data) {
+    console.log(`  Total tokens: ${item.total_tokens}`);
+    console.log(`  Token IDs: [${item.token_ids.join(", ")}]`);
+  }
+}
+
+async function main() {
+  await tokenize();
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@volcengine/ark-runtime",
+  "version": "1.0.0",
+  "files": [
+    "dist",
+    "src",
+    "example",
+    "package.json"
+  ],
+  "description": "Ark runtime data-plane client for model inference",
+  "license": "Apache-2.0",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.mjs",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.mjs",
+      "require": "./dist/cjs/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "axios": "^1.13.6",
+    "@volcengine/ark": "1.0.1"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.8.0",
+    "@types/uuid": "^10.0.0",
+    "axios-mock-adapter": "^2.1.0",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.5",
+    "typescript": "^5.2.2"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "rslib build",
+    "dev": "rslib build --watch",
+    "clean": "rm -rf dist",
+    "test": "jest",
+    "test:e2e": "ARK_E2E=1 jest --testPathPattern=e2e"
+  }
+}