@volcengine/ark-runtime 1.0.0

package/example/bot-chat.ts

@@ -0,0 +1,66 @@
+/**
+ * Bot 对话示例 (Doubao Bot)
+ * 对齐 Go SDK: example/bot/main.go
+ */
+import { ArkRuntimeClient } from "@volcengine/ark-runtime";
+
+const client = ArkRuntimeClient.withApiKey(process.env.ARK_API_KEY!);
+const BOT_ID = process.env.ARK_BOT_ID ?? "bot-xxxxx"; // 替换为实际 Bot ID
+
+async function botChatNonStream() {
+  console.log("----- Bot 非流式对话 -----");
+
+  const response = await client.createBotChatCompletion({
+    model: BOT_ID,
+    bot_id: BOT_ID,
+    messages: [{ role: "user", content: "介绍一下火山引擎" }],
+  });
+
+  console.log("Response:", response.choices[0].message.content);
+
+  // Bot 可能返回引用信息
+  if (response.references && response.references.length > 0) {
+    console.log("\nReferences:");
+    for (const ref of response.references) {
+      console.log(`  - ${ref.title}: ${ref.url}`);
+    }
+  }
+
+  // Bot 使用统计
+  if (response.bot_usage) {
+    console.log("\nBot Usage:", JSON.stringify(response.bot_usage, null, 2));
+  }
+}
+
+async function botChatStream() {
+  console.log("\n----- Bot 流式对话 -----");
+
+  const stream = await client.createBotChatCompletionStream({
+    model: BOT_ID,
+    bot_id: BOT_ID,
+    messages: [{ role: "user", content: "介绍一下火山引擎" }],
+  });
+
+  process.stdout.write("Streaming: ");
+  for await (const chunk of stream) {
+    if (chunk.choices?.[0]?.delta?.content) {
+      process.stdout.write(chunk.choices[0].delta.content);
+    }
+
+    // 流式中也可能包含引用
+    if (chunk.references && chunk.references.length > 0) {
+      console.log("\nReferences:");
+      for (const ref of chunk.references) {
+        console.log(`  - ${ref.title}: ${ref.url}`);
+      }
+    }
+  }
+  console.log();
+}
+
+async function main() {
+  await botChatNonStream();
+  await botChatStream();
+}
+
+main().catch(console.error);

package/example/chat-completion-function-call.ts

@@ -0,0 +1,141 @@
+/**
+ * 函数调用 (Function Calling / Tool Use) 示例
+ * 对齐 Go SDK: example/completion_function_call/main.go
+ */
+import { ArkRuntimeClient } from "@volcengine/ark-runtime";
+import type {
+  ChatCompletionMessage,
+  Tool,
+  ToolCall,
+} from "@volcengine/ark-runtime";
+
+const client = ArkRuntimeClient.withApiKey(process.env.ARK_API_KEY!);
+const MODEL = "doubao-seed-2-0-pro-260215";
+
+// 定义工具
+const tools: Tool[] = [
+  {
+    type: "function",
+    function: {
+      name: "get_current_weather",
+      description: "获取指定城市的当前天气",
+      parameters: {
+        type: "object",
+        properties: {
+          location: {
+            type: "string",
+            description: "城市名称，比如 北京",
+          },
+          unit: {
+            type: "string",
+            enum: ["celsius", "fahrenheit"],
+            description: "温度单位",
+          },
+        },
+        required: ["location"],
+      },
+    },
+  },
+];
+
+// 模拟的天气查询函数
+function getWeather(location: string, unit = "celsius"): string {
+  return JSON.stringify({
+    location,
+    temperature: unit === "celsius" ? "25" : "77",
+    unit,
+    description: "晴天",
+  });
+}
+
+async function functionCallNonStream() {
+  console.log("----- 非流式函数调用 -----");
+
+  const messages: ChatCompletionMessage[] = [
+    { role: "user", content: "北京今天天气怎么样？" },
+  ];
+
+  // 第一次调用：模型返回 tool_calls
+  const response = await client.createChatCompletion({
+    model: MODEL,
+    messages,
+    tools,
+  });
+
+  const assistantMsg = response.choices[0].message;
+  console.log("Tool calls:", JSON.stringify(assistantMsg.tool_calls, null, 2));
+
+  if (assistantMsg.tool_calls) {
+    // 追加 assistant 消息
+    messages.push(assistantMsg);
+
+    // 执行每个 tool call 并追加结果
+    for (const toolCall of assistantMsg.tool_calls) {
+      const args = JSON.parse(toolCall.function.arguments ?? "{}");
+      const result = getWeather(args.location, args.unit);
+      messages.push({
+        role: "tool",
+        tool_call_id: toolCall.id,
+        content: result,
+      });
+    }
+
+    // 第二次调用：模型基于工具结果生成最终回复
+    const finalResponse = await client.createChatCompletion({
+      model: MODEL,
+      messages,
+      tools,
+    });
+
+    console.log("Final:", finalResponse.choices[0].message.content);
+  }
+}
+
+async function functionCallStream() {
+  console.log("\n----- 流式函数调用 -----");
+
+  const stream = await client.createChatCompletionStream({
+    model: MODEL,
+    messages: [{ role: "user", content: "北京今天天气怎么样？" }],
+    tools,
+  });
+
+  // 聚合 tool call 参数（流式时 arguments 是分片的）
+  const toolCalls = new Map<number, { id: string; name: string; args: string }>();
+
+  for await (const chunk of stream) {
+    const delta = chunk.choices?.[0]?.delta;
+    if (!delta) continue;
+
+    if (delta.content) {
+      process.stdout.write(delta.content);
+    }
+
+    if (delta.tool_calls) {
+      for (const tc of delta.tool_calls) {
+        const idx = tc.index ?? 0;
+        if (!toolCalls.has(idx)) {
+          toolCalls.set(idx, { id: tc.id, name: tc.function?.name ?? "", args: "" });
+        }
+        const existing = toolCalls.get(idx)!;
+        if (tc.function?.arguments) {
+          existing.args += tc.function.arguments;
+        }
+      }
+    }
+  }
+
+  if (toolCalls.size > 0) {
+    console.log("\nStreamed tool calls:");
+    for (const [idx, tc] of toolCalls) {
+      console.log(`  [${idx}] ${tc.name}(${tc.args})`);
+    }
+  }
+}
+
+async function main() {
+  await functionCallNonStream();
+  await functionCallStream();
+}
+
+main().catch(console.error);

package/example/chat-completion-reasoning.ts

@@ -0,0 +1,64 @@
+/**
+ * 推理 (Reasoning / Thinking) 模式示例
+ * 对齐 Go SDK: example/completion_reasoning/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 reasoningStream() {
+  console.log("----- 流式推理模式 -----");
+
+  const stream = await client.createChatCompletionStream({
+    model: MODEL,
+    messages: [{ role: "user", content: "请解释为什么 0.1 + 0.2 !== 0.3 in JavaScript" }],
+    thinking: { type: "enabled" },
+  });
+
+  let inReasoning = false;
+  for await (const chunk of stream) {
+    const delta = chunk.choices?.[0]?.delta;
+    if (!delta) continue;
+
+    if (delta.reasoning_content) {
+      if (!inReasoning) {
+        console.log("[Reasoning]");
+        inReasoning = true;
+      }
+      process.stdout.write(delta.reasoning_content);
+    }
+
+    if (delta.content) {
+      if (inReasoning) {
+        console.log("\n[Output]");
+        inReasoning = false;
+      }
+      process.stdout.write(delta.content);
+    }
+  }
+  console.log();
+}
+
+async function reasoningNonStream() {
+  console.log("\n----- 非流式推理模式 -----");
+
+  const response = await client.createChatCompletion({
+    model: MODEL,
+    messages: [{ role: "user", content: "计算 123 * 456 的结果" }],
+    thinking: { type: "enabled" },
+  });
+
+  const msg = response.choices[0].message;
+  if (msg.reasoning_content) {
+    console.log("[Reasoning]:", msg.reasoning_content);
+  }
+  console.log("[Output]:", msg.content);
+}
+
+async function main() {
+  await reasoningStream();
+  await reasoningNonStream();
+}
+
+main().catch(console.error);

package/example/chat-completion-vision.ts

@@ -0,0 +1,70 @@
+/**
+ * 多模态/视觉对话示例
+ * 对齐 Go SDK: example/completion_vision/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 visionChat() {
+  console.log("----- 视觉对话 -----");
+
+  const response = await client.createChatCompletion({
+    model: MODEL,
+    messages: [
+      {
+        role: "user",
+        content: [
+          { type: "text", text: "这张图片里有什么？" },
+          {
+            type: "image_url",
+            image_url: {
+              url: "https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png",
+            },
+          },
+        ],
+      },
+    ],
+  });
+
+  console.log("Response:", response.choices[0].message.content);
+}
+
+async function visionChatStream() {
+  console.log("\n----- 视觉流式对话 -----");
+
+  const stream = await client.createChatCompletionStream({
+    model: MODEL,
+    messages: [
+      {
+        role: "user",
+        content: [
+          { type: "text", text: "详细描述这张图片" },
+          {
+            type: "image_url",
+            image_url: {
+              url: "https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png",
+              detail: "high",
+            },
+          },
+        ],
+      },
+    ],
+  });
+
+  process.stdout.write("Streaming: ");
+  for await (const chunk of stream) {
+    if (chunk.choices?.[0]?.delta?.content) {
+      process.stdout.write(chunk.choices[0].delta.content);
+    }
+  }
+  console.log();
+}
+
+async function main() {
+  await visionChat();
+  await visionChatStream();
+}
+
+main().catch(console.error);

package/example/chat-completion.ts

@@ -0,0 +1,62 @@
+/**
+ * 基础对话补全示例
+ * Basic chat completion example (non-streaming + streaming)
+ *
+ * 对齐 Go SDK: example/completion/main.go
+ */
+import { ArkRuntimeClient } from "@volcengine/ark-runtime";
+
+// 使用 API Key 鉴权
+const client = ArkRuntimeClient.withApiKey(process.env.ARK_API_KEY!);
+
+// 也可以使用 AK/SK 鉴权（会自动获取 STS token）
+// const client = ArkRuntimeClient.withAkSk(
+//   process.env.VOLC_ACCESSKEY!,
+//   process.env.VOLC_SECRETKEY!,
+// );
+
+const MODEL = "doubao-seed-2-0-pro-260215";
+
+async function chatCompletion() {
+  console.log("----- 非流式对话 -----");
+
+  const response = await client.createChatCompletion({
+    model: MODEL,
+    messages: [
+      { role: "system", content: "你是一个有帮助的AI助手。" },
+      { role: "user", content: "请介绍一下北京的天气特点" },
+    ],
+  });
+
+  console.log("Response ID:", response.id);
+  console.log("Model:", response.model);
+  console.log("Content:", response.choices[0].message.content);
+  console.log("Usage:", JSON.stringify(response.usage));
+}
+
+async function chatCompletionStream() {
+  console.log("\n----- 流式对话 -----");
+
+  const stream = await client.createChatCompletionStream({
+    model: MODEL,
+    messages: [
+      { role: "system", content: "你是一个有帮助的AI助手。" },
+      { role: "user", content: "请介绍一下北京的天气特点" },
+    ],
+  });
+
+  process.stdout.write("Streaming: ");
+  for await (const chunk of stream) {
+    if (chunk.choices?.[0]?.delta?.content) {
+      process.stdout.write(chunk.choices[0].delta.content);
+    }
+  }
+  console.log();
+}
+
+async function main() {
+  await chatCompletion();
+  await chatCompletionStream();
+}
+
+main().catch(console.error);

package/example/content-generation.ts

@@ -0,0 +1,70 @@
+/**
+ * 内容/视频生成（异步任务）示例
+ * 对齐 Go SDK: example/content_generation/main.go
+ *
+ * 注意：仅支持 API Key 鉴权
+ */
+import { ArkRuntimeClient } from "@volcengine/ark-runtime";
+
+const client = ArkRuntimeClient.withApiKey(process.env.ARK_API_KEY!);
+const MODEL = process.env.ARK_VIDEO_MODEL ?? "seedance-1-0-lite";
+
+async function createTask() {
+  console.log("----- 创建内容生成任务 -----");
+
+  const task = await client.createContentGenerationTask({
+    model: MODEL,
+    content: [
+      { type: "text", text: "一只猫在草地上奔跑" },
+    ],
+  });
+
+  console.log("Task ID:", task.id);
+  return task.id;
+}
+
+async function pollTask(taskId: string) {
+  console.log("\n----- 轮询任务状态 -----");
+
+  let status = "running";
+  while (status === "running" || status === "queued") {
+    await new Promise((r) => setTimeout(r, 5000));
+
+    const result = await client.getContentGenerationTask(taskId);
+    status = result.status;
+    console.log(`  Status: ${status}`);
+
+    if (status === "succeeded") {
+      console.log("  Video URL:", result.content.video_url);
+      console.log("  Usage:", JSON.stringify(result.usage));
+      return;
+    }
+
+    if (status === "failed") {
+      console.log("  Error:", result.error?.message);
+      return;
+    }
+  }
+}
+
+async function listTasks() {
+  console.log("\n----- 列出任务 -----");
+
+  const response = await client.listContentGenerationTasks({
+    page_num: 1,
+    page_size: 5,
+  });
+
+  console.log(`Total: ${response.total}`);
+  for (const item of response.items) {
+    console.log(`  [${item.id}] status=${item.status}, model=${item.model}`);
+  }
+}
+
+async function main() {
+  const taskId = await createTask();
+  await pollTask(taskId);
+  await listTasks();
+}
+
+main().catch(console.error);

package/example/context.ts

@@ -0,0 +1,69 @@
+/**
+ * Context（上下文/会话管理）示例
+ * 对齐 Go SDK: example/context/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 contextChat() {
+  console.log("----- 创建 Context -----");
+
+  // 创建一个持久化的上下文（session 模式），TTL=3600 秒
+  const ctx = await client.createContext({
+    model: MODEL,
+    mode: "session",
+    messages: [
+      { role: "system", content: "你是一个数学助手，用简洁的方式回答问题。" },
+    ],
+    ttl: 3600,
+  });
+
+  console.log("Context ID:", ctx.id);
+  console.log("Mode:", ctx.mode);
+  console.log("Usage:", JSON.stringify(ctx.usage));
+
+  // 第一轮对话
+  console.log("\n----- 第一轮对话 -----");
+  const resp1 = await client.createContextChatCompletion({
+    model: MODEL,
+    context_id: ctx.id,
+    mode: "session",
+    messages: [{ role: "user", content: "1+1等于几？" }],
+  });
+  console.log("Answer:", resp1.choices[0].message.content);
+
+  // 第二轮对话（上下文自动保持）
+  console.log("\n----- 第二轮对话 -----");
+  const resp2 = await client.createContextChatCompletion({
+    model: MODEL,
+    context_id: ctx.id,
+    mode: "session",
+    messages: [{ role: "user", content: "再加3呢？" }],
+  });
+  console.log("Answer:", resp2.choices[0].message.content);
+
+  // 流式上下文对话
+  console.log("\n----- 流式上下文对话 -----");
+  const stream = await client.createContextChatCompletionStream({
+    model: MODEL,
+    context_id: ctx.id,
+    mode: "session",
+    messages: [{ role: "user", content: "再乘以2呢？" }],
+  });
+
+  process.stdout.write("Streaming: ");
+  for await (const chunk of stream) {
+    if (chunk.choices?.[0]?.delta?.content) {
+      process.stdout.write(chunk.choices[0].delta.content);
+    }
+  }
+  console.log();
+}
+
+async function main() {
+  await contextChat();
+}
+
+main().catch(console.error);

package/example/embeddings.ts

@@ -0,0 +1,31 @@
+/**
+ * 文本 Embedding 示例
+ * 对齐 Go SDK: example/embeddings/main.go
+ */
+import { ArkRuntimeClient } from "@volcengine/ark-runtime";
+
+const client = ArkRuntimeClient.withApiKey(process.env.ARK_API_KEY!);
+const MODEL = "doubao-embedding-large";
+
+async function createEmbedding() {
+  console.log("----- 文本 Embedding -----");
+
+  const response = await client.createEmbeddings({
+    model: MODEL,
+    input: ["天空是蓝色的", "草地是绿色的"],
+  });
+
+  console.log("Model:", response.model);
+  console.log("Object:", response.object);
+  console.log("Usage:", JSON.stringify(response.usage));
+
+  for (const item of response.data) {
+    console.log(`  [${item.index}] dimension=${item.embedding.length}, first 5:`, item.embedding.slice(0, 5));
+  }
+}
+
+async function main() {
+  await createEmbedding();
+}
+
+main().catch(console.error);

package/example/file-upload.ts

@@ -0,0 +1,53 @@
+/**
+ * 文件上传与管理示例
+ * 对齐 Go SDK: example/file.go (内嵌在 responses/video 示例中)
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { ArkRuntimeClient } from "@volcengine/ark-runtime";
+
+const client = ArkRuntimeClient.withApiKey(process.env.ARK_API_KEY!);
+
+async function fileOperations() {
+  console.log("----- 文件上传 -----");
+
+  // 上传文件（这里创建一个临时文件作为示例）
+  const tmpFile = path.join("/tmp", "ark-test-upload.txt");
+  fs.writeFileSync(tmpFile, "Hello, this is a test file for upload.");
+
+  const fileMeta = await client.uploadFile({
+    file: fs.createReadStream(tmpFile) as any,
+    purpose: "user_data",
+  });
+
+  console.log("File ID:", fileMeta.id);
+  console.log("Filename:", fileMeta.filename);
+  console.log("Status:", fileMeta.status);
+
+  // 查询文件
+  console.log("\n----- 查询文件 -----");
+  const retrieved = await client.retrieveFile(fileMeta.id);
+  console.log("Retrieved:", retrieved.id, retrieved.status);
+
+  // 列出文件
+  console.log("\n----- 列出文件 -----");
+  const list = await client.listFiles({ limit: 5 });
+  console.log(`Total files listed: ${list.data?.length ?? 0}`);
+  for (const f of list.data ?? []) {
+    console.log(`  [${f.id}] ${f.filename} (${f.status})`);
+  }
+
+  // 删除文件
+  console.log("\n----- 删除文件 -----");
+  const deleteResult = await client.deleteFile(fileMeta.id);
+  console.log("Deleted:", deleteResult.deleted);
+
+  // 清理临时文件
+  fs.unlinkSync(tmpFile);
+}
+
+async function main() {
+  await fileOperations();
+}
+
+main().catch(console.error);

package/example/images.ts

@@ -0,0 +1,74 @@
+/**
+ * 图片生成示例 (Seedream / Seededit)
+ * 对齐 Go SDK: example/images/main.go
+ *
+ * 注意：图片生成仅支持 API Key 鉴权
+ */
+import { ArkRuntimeClient } from "@volcengine/ark-runtime";
+
+const client = ArkRuntimeClient.withApiKey(process.env.ARK_API_KEY!);
+const MODEL = process.env.ARK_IMAGE_MODEL ?? "seedream-3-0";
+
+async function generateImageURL() {
+  console.log("----- 生成图片 (URL 格式) -----");
+
+  const response = await client.generateImages({
+    model: MODEL,
+    prompt: "一只可爱的橘猫在花园里玩耍",
+    response_format: "url",
+    size: "1024x1024",
+    watermark: false,
+  });
+
+  console.log("Created:", response.created);
+  for (const img of response.data) {
+    console.log("  URL:", img.url);
+    console.log("  Size:", img.size);
+  }
+}
+
+async function generateImageBase64() {
+  console.log("\n----- 生成图片 (Base64 格式) -----");
+
+  const response = await client.generateImages({
+    model: MODEL,
+    prompt: "一座雪山的油画风景",
+    response_format: "b64_json",
+    size: "512x512",
+  });
+
+  for (const img of response.data) {
+    console.log("  Base64 length:", img.b64_json?.length);
+    console.log("  Size:", img.size);
+  }
+}
+
+async function generateImageStream() {
+  console.log("\n----- 流式图片生成 -----");
+
+  const stream = await client.generateImagesStream({
+    model: MODEL,
+    prompt: "赛博朋克风格的城市夜景",
+    response_format: "url",
+    sequential_image_generation: "auto",
+    sequential_image_generation_options: { max_images: 3 },
+  });
+
+  for await (const event of stream) {
+    console.log(`  [${event.type}] index=${event.image_index}`);
+    if (event.url) {
+      console.log(`    URL: ${event.url}`);
+    }
+    if (event.error) {
+      console.log(`    Error: ${event.error.message}`);
+    }
+  }
+}
+
+async function main() {
+  await generateImageURL();
+  await generateImageBase64();
+  await generateImageStream();
+}
+
+main().catch(console.error);