@volcengine/ark-runtime 1.0.0

package/src/types/chat-completion.ts

@@ -0,0 +1,228 @@
+import type { Usage, HttpHeaders } from "./common";
+
+// Role constants
+export const ChatMessageRoleSystem = "system";
+export const ChatMessageRoleUser = "user";
+export const ChatMessageRoleAssistant = "assistant";
+export const ChatMessageRoleTool = "tool";
+
+// ImageURL detail
+export type ImageURLDetail = "high" | "low" | "auto";
+
+// Reasoning effort
+export type ReasoningEffort = "minimal" | "low" | "medium" | "high";
+
+export interface ChatMessageImageURL {
+  url: string;
+  detail?: ImageURLDetail;
+}
+
+export interface ChatMessageVideoURL {
+  url: string;
+  fps?: number;
+}
+
+// Content part type
+export type ChatCompletionMessageContentPartType =
+  | "text"
+  | "image_url"
+  | "video_url";
+
+export interface ChatCompletionMessageContentPart {
+  type?: ChatCompletionMessageContentPartType;
+  text?: string;
+  image_url?: ChatMessageImageURL;
+  video_url?: ChatMessageVideoURL;
+}
+
+// In TS, the union type naturally handles Go's custom MarshalJSON
+export type ChatCompletionMessageContent =
+  | string
+  | ChatCompletionMessageContentPart[];
+
+export interface ChatCompletionMessage {
+  role: string;
+  content?: ChatCompletionMessageContent | null;
+  reasoning_content?: string;
+  name?: string;
+  function_call?: FunctionCall;
+  tool_calls?: ToolCall[];
+  tool_call_id?: string;
+}
+
+export interface ToolCall {
+  id: string;
+  type: ToolType;
+  function: FunctionCall;
+  index?: number;
+}
+
+export interface FunctionCall {
+  name?: string;
+  arguments?: string;
+}
+
+// Thinking
+export type ThinkingType = "enabled" | "disabled" | "auto";
+
+export interface Thinking {
+  type: ThinkingType;
+}
+
+// Stream options
+export interface StreamOptions {
+  include_usage?: boolean;
+  chunk_include_usage?: boolean;
+}
+
+// Tool type
+export type ToolType = "function";
+
+export interface Tool {
+  type: ToolType;
+  function?: FunctionDefinition;
+}
+
+// Tool choice
+export const ToolChoiceAuto = "auto";
+export const ToolChoiceNone = "none";
+export const ToolChoiceRequired = "required";
+
+export interface ToolChoice {
+  type: ToolType;
+  function?: ToolChoiceFunction;
+}
+
+export interface ToolChoiceFunction {
+  name: string;
+}
+
+export interface FunctionDefinition {
+  name: string;
+  description?: string;
+  parameters?: unknown;
+}
+
+// LogProbs
+export interface TopLogProbs {
+  token: string;
+  logprob: number;
+  bytes?: number[];
+}
+
+export interface LogProb {
+  token: string;
+  logprob: number;
+  bytes?: number[];
+  top_logprobs: TopLogProbs[];
+}
+
+export interface LogProbs {
+  content: LogProb[];
+}
+
+// Response format
+export type ResponseFormatType = "json_schema" | "json_object" | "text";
+
+export interface ResponseFormatJSONSchema {
+  name: string;
+  description: string;
+  schema: unknown;
+  strict: boolean;
+}
+
+export interface ResponseFormat {
+  type: ResponseFormatType;
+  json_schema?: ResponseFormatJSONSchema;
+  /** @deprecated use json_schema instead */
+  schema?: unknown;
+}
+
+// Finish reason
+export type FinishReason =
+  | "stop"
+  | "length"
+  | "function_call"
+  | "tool_calls"
+  | "content_filter"
+  | null;
+
+// Moderation hit type
+export type ModerationHitType = "violence" | "severe_violation";
+
+// Chat completion request
+export interface ChatCompletionRequest {
+  model: string;
+  messages: ChatCompletionMessage[];
+  max_tokens?: number;
+  temperature?: number;
+  top_p?: number;
+  stream?: boolean;
+  stop?: string[];
+  frequency_penalty?: number;
+  logit_bias?: Record<string, number>;
+  logprobs?: boolean;
+  top_logprobs?: number;
+  user?: string;
+  function_call?: unknown;
+  tools?: Tool[];
+  tool_choice?: string | ToolChoice;
+  stream_options?: StreamOptions;
+  presence_penalty?: number;
+  repetition_penalty?: number;
+  n?: number;
+  response_format?: ResponseFormat;
+  parallel_tool_calls?: boolean;
+  service_tier?: string;
+  thinking?: Thinking;
+  max_completion_tokens?: number;
+  reasoning_effort?: ReasoningEffort;
+}
+
+// Chat completion choice
+export interface ChatCompletionChoice {
+  index: number;
+  message: ChatCompletionMessage;
+  finish_reason: FinishReason;
+  moderation_hit_type?: ModerationHitType;
+  logprobs?: LogProbs;
+}
+
+// Chat completion response
+export interface ChatCompletionResponse {
+  id: string;
+  object: string;
+  created: number;
+  model: string;
+  service_tier?: string;
+  choices: ChatCompletionChoice[];
+  usage: Usage;
+  headers?: HttpHeaders;
+}
+
+// Stream types
+export interface ChatCompletionStreamChoiceDelta {
+  content?: string;
+  role?: string;
+  reasoning_content?: string;
+  function_call?: FunctionCall;
+  tool_calls?: ToolCall[];
+}
+
+export interface ChatCompletionStreamChoice {
+  index: number;
+  delta: ChatCompletionStreamChoiceDelta;
+  logprobs?: LogProbs;
+  finish_reason: FinishReason;
+  moderation_hit_type?: ModerationHitType;
+}
+
+export interface ChatCompletionStreamResponse {
+  id: string;
+  object: string;
+  created: number;
+  model: string;
+  service_tier?: string;
+  choices: ChatCompletionStreamChoice[];
+  usage?: Usage;
+}

package/src/types/common.ts

@@ -0,0 +1,37 @@
+// Header constants
+export const ClientRequestHeader = "X-Client-Request-Id";
+export const RetryAfterHeader = "Retry-After";
+export const ClientSessionTokenHeader = "X-Session-Token";
+export const ClientEncryptInfoHeader = "X-Encrypt-Info";
+export const ClientIsEncryptedHeader = "x-is-encrypted";
+
+// Timeout defaults (seconds)
+export const DefaultMandatoryRefreshTimeout = 10 * 60; // 10 min
+export const DefaultAdvisoryRefreshTimeout = 30 * 60; // 30 min
+export const DefaultStsTimeout = 7 * 24 * 60 * 60; // 7 days
+
+// Retry defaults
+export const InitialRetryDelay = 0.5;
+export const MaxRetryDelay = 8.0;
+export const ErrorRetryBaseDelayMs = 500;
+export const ErrorRetryMaxDelayMs = 8000;
+
+export interface PromptTokensDetail {
+  cached_tokens: number;
+  provisioned_tokens?: number;
+}
+
+export interface CompletionTokensDetails {
+  reasoning_tokens: number;
+  provisioned_tokens?: number;
+}
+
+export interface Usage {
+  prompt_tokens: number;
+  completion_tokens: number;
+  total_tokens: number;
+  prompt_tokens_details: PromptTokensDetail;
+  completion_tokens_details: CompletionTokensDetails;
+}
+
+export type HttpHeaders = Record<string, string>;

package/src/types/content-generation.ts

@@ -0,0 +1,135 @@
+import type { Usage, HttpHeaders } from "./common";
+
+export type ContentGenerationContentItemType =
+  | "text"
+  | "image_url"
+  | "draft_task";
+
+export const StatusSucceeded = "succeeded";
+export const StatusCancelled = "cancelled";
+export const StatusFailed = "failed";
+export const StatusRunning = "running";
+export const StatusQueued = "queued";
+
+export interface ImageURL {
+  url: string;
+}
+
+export interface DraftTask {
+  id: string;
+}
+
+export interface CreateContentGenerationContentItem {
+  type: ContentGenerationContentItemType;
+  text?: string;
+  image_url?: ImageURL;
+  role?: string;
+  draft_task?: DraftTask;
+}
+
+export interface CreateContentGenerationTaskRequest {
+  model: string;
+  content: CreateContentGenerationContentItem[];
+  callback_url?: string;
+  return_last_frame?: boolean;
+  service_tier?: string;
+  execution_expires_after?: number;
+  generate_audio?: boolean;
+  draft?: boolean;
+  camera_fixed?: boolean;
+  watermark?: boolean;
+  seed?: number;
+  resolution?: string;
+  ratio?: string;
+  duration?: number;
+  frames?: number;
+  /** Extra fields merged into request body */
+  [key: string]: unknown;
+}
+
+export interface CreateContentGenerationTaskResponse {
+  id: string;
+  headers?: HttpHeaders;
+}
+
+export interface ContentGenerationError {
+  code: string;
+  message: string;
+}
+
+export interface Content {
+  video_url: string;
+  last_frame_url: string;
+  file_url: string;
+}
+
+export interface GetContentGenerationTaskResponse {
+  id: string;
+  model: string;
+  status: string;
+  error?: ContentGenerationError;
+  content: Content;
+  usage: Usage;
+  subdivisionlevel?: string;
+  fileformat?: string;
+  frames?: number;
+  framespersecond?: number;
+  resolution?: string;
+  ratio?: string;
+  duration?: number;
+  created_at: number;
+  updated_at: number;
+  seed?: number;
+  revised_prompt?: string;
+  service_tier?: string;
+  execution_expires_after?: number;
+  generate_audio?: boolean;
+  draft?: boolean;
+  draft_task_id?: string;
+  headers?: HttpHeaders;
+}
+
+export interface ListContentGenerationTasksFilter {
+  status?: string;
+  task_ids?: string[];
+  model?: string;
+  service_tier?: string;
+}
+
+export interface ListContentGenerationTasksRequest {
+  page_num?: number;
+  page_size?: number;
+  filter?: ListContentGenerationTasksFilter;
+}
+
+export interface ListContentGenerationTaskItem {
+  id: string;
+  model: string;
+  status: string;
+  failure_reason?: ContentGenerationError;
+  content: Content;
+  usage: Usage;
+  subdivisionlevel?: string;
+  fileformat?: string;
+  frames?: number;
+  framespersecond?: number;
+  created_at: number;
+  updated_at: number;
+  seed?: number;
+  revised_prompt?: string;
+  service_tier?: string;
+  execution_expires_after?: number;
+  generate_audio?: boolean;
+  draft?: boolean;
+  draft_task_id?: string;
+}
+
+export interface ListContentGenerationTasksResponse {
+  total: number;
+  items: ListContentGenerationTaskItem[];
+  headers?: HttpHeaders;
+}
+
+export interface DeleteContentGenerationTaskRequest {
+  id: string;
+}

package/src/types/context.ts

@@ -0,0 +1,59 @@
+import type { Usage, HttpHeaders } from "./common";
+import type {
+  ChatCompletionMessage,
+  Tool,
+  ToolChoice,
+  StreamOptions,
+} from "./chat-completion";
+
+export type TruncationStrategyType = "last_history_tokens" | "rolling_tokens";
+
+export type ContextMode = "session" | "common_prefix";
+
+export interface TruncationStrategy {
+  type: TruncationStrategyType;
+  last_history_tokens?: number;
+  rolling_tokens?: boolean;
+  max_window_tokens?: number;
+  rolling_window_tokens?: number;
+}
+
+export interface CreateContextRequest {
+  model: string;
+  mode: ContextMode;
+  messages: ChatCompletionMessage[];
+  ttl?: number;
+  truncation_strategy?: TruncationStrategy;
+}
+
+export interface CreateContextResponse {
+  id: string;
+  mode: ContextMode;
+  model: string;
+  ttl?: number;
+  truncation_strategy?: TruncationStrategy;
+  usage: Usage;
+  headers?: HttpHeaders;
+}
+
+export interface ContextChatCompletionRequest {
+  context_id: string;
+  mode: ContextMode;
+  model: string;
+  messages: ChatCompletionMessage[];
+  max_tokens?: number;
+  temperature?: number;
+  top_p?: number;
+  stream?: boolean;
+  stop?: string[];
+  frequency_penalty?: number;
+  logit_bias?: Record<string, number>;
+  logprobs?: boolean;
+  top_logprobs?: number;
+  user?: string;
+  function_call?: unknown;
+  tools?: Tool[];
+  tool_choice?: string | ToolChoice;
+  stream_options?: StreamOptions;
+  metadata?: Record<string, unknown>;
+}

package/src/types/embeddings.ts

@@ -0,0 +1,74 @@
+import type { Usage, HttpHeaders } from "./common";
+
+export type EmbeddingEncodingFormat = "float" | "base64";
+
+export interface EmbeddingRequest {
+  input: string | string[] | number[][] ;
+  model: string;
+  user?: string;
+  encoding_format?: EmbeddingEncodingFormat;
+  dimensions?: number;
+}
+
+export interface Embedding {
+  object: string;
+  embedding: number[];
+  index: number;
+}
+
+export interface EmbeddingResponse {
+  id: string;
+  created: number;
+  object: string;
+  data: Embedding[];
+  model: string;
+  usage: Usage;
+  headers?: HttpHeaders;
+}
+
+// Base64 embedding support
+export interface Base64Embedding {
+  object: string;
+  embedding: string; // base64 encoded
+  index: number;
+}
+
+export interface EmbeddingResponseBase64 {
+  object: string;
+  data: Base64Embedding[];
+  model: string;
+  usage: Usage;
+  headers?: HttpHeaders;
+}
+
+/**
+ * Decode a base64-encoded embedding into a float32 array.
+ */
+export function decodeBase64Embedding(b64: string): number[] {
+  const buf = Buffer.from(b64, "base64");
+  const floats: number[] = [];
+  for (let i = 0; i < buf.length; i += 4) {
+    floats.push(buf.readFloatLE(i));
+  }
+  return floats;
+}
+
+/**
+ * Convert a base64 embedding response to a standard embedding response.
+ */
+export function base64ToEmbeddingResponse(
+  resp: EmbeddingResponseBase64,
+): EmbeddingResponse {
+  return {
+    id: "",
+    created: 0,
+    object: resp.object,
+    model: resp.model,
+    usage: resp.usage,
+    data: resp.data.map((item) => ({
+      object: item.object,
+      embedding: decodeBase64Embedding(item.embedding),
+      index: item.index,
+    })),
+  };
+}

package/src/types/error.ts

@@ -0,0 +1,93 @@
+import { HttpRequestError, HttpRequestErrorName } from "./http-request-error";
+
+export class ArkAPIError extends HttpRequestError {
+  code?: string;
+  param?: string;
+  type: string;
+  requestId: string;
+
+  constructor(opts: {
+    message: string;
+    code?: string;
+    param?: string;
+    type: string;
+    httpStatusCode: number;
+    requestId: string;
+  }) {
+    super("ApiException", opts.message, opts.httpStatusCode, undefined, undefined);
+    (this as any).name = "ArkAPIError";
+    this.code = opts.code;
+    this.param = opts.param;
+    this.type = opts.type;
+    this.requestId = opts.requestId;
+  }
+
+  get httpStatusCode(): number {
+    return this.status ?? 0;
+  }
+
+  override toString(): string {
+    return `Error code: ${this.httpStatusCode} - ${JSON.stringify({
+      code: this.code,
+      message: this.message,
+      param: this.param,
+      type: this.type,
+      request_id: this.requestId,
+    })}`;
+  }
+}
+
+export class ArkRequestError extends HttpRequestError {
+  requestId: string;
+
+  constructor(opts: {
+    httpStatusCode: number;
+    message: string;
+    requestId: string;
+    cause?: Error;
+  }) {
+    super("NetworkError", opts.message, opts.httpStatusCode, undefined, opts.cause);
+    (this as any).name = "ArkRequestError";
+    this.requestId = opts.requestId;
+  }
+
+  get httpStatusCode(): number {
+    return this.status ?? 0;
+  }
+
+  override toString(): string {
+    return `RequestError code: ${this.httpStatusCode}, err: ${this.originalError?.message ?? this.message}, request_id: ${this.requestId}`;
+  }
+}
+
+export interface ErrorResponse {
+  error?: {
+    code?: string;
+    message: string;
+    param?: string;
+    type: string;
+    request_id?: string;
+  };
+}
+
+export const ErrTooManyEmptyStreamMessages = new Error(
+  "stream has sent too many empty messages",
+);
+export const ErrChatCompletionStreamNotSupported = new Error(
+  "streaming is not supported with this method, please use CreateChatCompletionStream",
+);
+export const ErrContentFieldsMisused = new Error(
+  "can't use both Content and MultiContent properties simultaneously",
+);
+export const ErrBodyWithoutEndpoint = new Error(
+  "can't fetch endpoint sts token without endpoint",
+);
+export const ErrBodyWithoutBot = new Error(
+  "can't fetch bot sts token without bot id",
+);
+export const ErrAKSKNotSupported = new Error(
+  "ak&sk authentication is currently not supported for this method, please use api key instead",
+);
+export const ErrBodyWithoutProjectName = new Error(
+  "project name is required for preset endpoint",
+);

package/src/types/file.ts

@@ -0,0 +1,76 @@
+import type { HttpHeaders } from "./common";
+
+// Constants
+export const PurposeUserData = "user_data";
+export const FileStatusActive = "active";
+export const FileStatusProcessing = "processing";
+export const FileStatusFailed = "failed";
+export const ObjectTypeList = "list";
+export const ObjectTypeFile = "file";
+export const OrderAsc = "asc";
+export const OrderDesc = "desc";
+
+export type FilePurpose = string;
+export type FileStatus = string;
+export type FileObjectType = string;
+export type FileOrder = "asc" | "desc";
+
+export interface FileError {
+  code: string;
+  message: string;
+  param: string;
+  type: string;
+}
+
+export interface Video {
+  fps?: number;
+}
+
+export interface PreprocessConfigs {
+  video?: Video;
+}
+
+export interface FileMeta {
+  object: FileObjectType;
+  id: string;
+  purpose: FilePurpose;
+  filename: string;
+  bytes?: number;
+  mime_type?: string;
+  created_at: number;
+  expire_at: number;
+  status: FileStatus;
+  error?: FileError;
+  preprocess_configs?: PreprocessConfigs;
+  headers?: HttpHeaders;
+}
+
+export interface UploadFileRequest {
+  file: Blob | Buffer | ReadableStream;
+  purpose: FilePurpose;
+  preprocess_configs?: PreprocessConfigs;
+  expire_at?: number;
+}
+
+export interface ListFilesRequest {
+  purpose?: FilePurpose;
+  after?: string;
+  limit?: number;
+  order?: FileOrder;
+}
+
+export interface ListFilesResponse {
+  object: FileObjectType;
+  data: FileMeta[];
+  first_id: string;
+  last_id: string;
+  has_more: boolean;
+  headers?: HttpHeaders;
+}
+
+export interface DeleteFileResponse {
+  object: FileObjectType;
+  id: string;
+  deleted: boolean;
+  headers?: HttpHeaders;
+}