TypeScript SDK - Avala Documentation

インストール

npm install @avala-ai/sdk

yarn add @avala-ai/sdk

pnpm add @avala-ai/sdk

クイックスタート

import Avala from "@avala-ai/sdk";

const avala = new Avala({ apiKey: "your-api-key" });

const datasets = await avala.datasets.list();
for (const dataset of datasets.items) {
  console.log(dataset.name, dataset.uid);
}

アカウントの作成

signup 関数は新しい Avala アカウントを作成し、API キーを返します。認証は不要です。

import { signup } from "@avala-ai/sdk";

const result = await signup({
  email: "dev@acme.com",
  password: "SecurePass123!",
  firstName: "Jane",       // optional
  lastName: "Doe",         // optional
});

console.log(`User: ${result.user.email}`);
console.log(`API Key: ${result.apiKey}`);

返された API キーを使ってクライアントを初期化します：

import Avala, { signup } from "@avala-ai/sdk";

const { apiKey } = await signup({ email: "dev@acme.com", password: "SecurePass123!" });
const avala = new Avala({ apiKey });

認証

SDK は、すべてのリクエストで X-Avala-Api-Key ヘッダーを通じて送信される Avala API キーを使用して認証します。キーを直接渡すか、SDK に環境変数から読み取らせることができます。 オプション 1: キーを直接渡す

import Avala from "@avala-ai/sdk";

const avala = new Avala({ apiKey: "your-api-key" });

オプション 2: 環境変数を使用する

export AVALA_API_KEY="your-api-key"

import Avala from "@avala-ai/sdk";

// 環境変数から AVALA_API_KEY を自動的に読み取ります
const avala = new Avala();

データセットの操作

TypeScript SDK は現在データセットに対して読み取り専用です — データセットの一覧表示と取得は可能ですが、作成、更新、削除はできません。アップロードやミューテーションには REST API を使用してください。

データセットの一覧表示

const datasets = await avala.datasets.list();

for (const dataset of datasets.items) {
  console.log(`${dataset.name} (${dataset.uid})`);
  console.log(`  Items: ${dataset.itemCount}`);
  console.log(`  Created: ${dataset.createdAt}`);
}

データセットの取得

const dataset = await avala.datasets.get("550e8400-e29b-41d4-a716-446655440000");

console.log(dataset.name);
console.log(dataset.slug);
console.log(dataset.itemCount);

プロジェクトの操作

プロジェクトの一覧表示

const projects = await avala.projects.list();

for (const project of projects.items) {
  console.log(`${project.name} (${project.uid})`);
  console.log(`  Status: ${project.status}`);
  console.log(`  Created: ${project.createdAt}`);
}

プロジェクトの取得

const project = await avala.projects.get("770a9600-a40d-63f6-c938-668877660000");

console.log(project.name);
console.log(project.status);

タスクの操作

タスクの一覧表示

const tasks = await avala.tasks.list({
  project: "770a9600-a40d-63f6-c938-668877660000",
  status: "pending",
});

for (const task of tasks.items) {
  console.log(`${task.uid} — ${task.name} (${task.status})`);
}

タスクの取得

const task = await avala.tasks.get("990c1800-b62f-85a8-e150-880099880000");

console.log(task.name);
console.log(task.status);

エクスポートの操作

エクスポートの作成

const exportJob = await avala.exports.create({
  project: "770a9600-a40d-63f6-c938-668877660000",
});

console.log(`Export started: ${exportJob.uid}`);
console.log(`Status: ${exportJob.status}`);

完了のポーリング

let exportJob = await avala.exports.create({
  project: "770a9600-a40d-63f6-c938-668877660000",
});

while (exportJob.status !== "completed") {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  exportJob = await avala.exports.get(exportJob.uid);
  console.log(`Status: ${exportJob.status}`);
}

console.log(`Download: ${exportJob.downloadUrl}`);

TypeScript 型

SDK はすべての API オブジェクトの完全な TypeScript インターフェースをエクスポートします。関数や変数の型付けに使用してください。

import Avala from "@avala-ai/sdk";
import type { Dataset, Project, Export, Task, CursorPage } from "@avala-ai/sdk";

function processDataset(dataset: Dataset): void {
  console.log(dataset.name);       // string
  console.log(dataset.uid);        // string
  console.log(dataset.itemCount);  // number
  console.log(dataset.createdAt);  // string | null
}

function processTask(task: Task): void {
  console.log(task.uid);           // string
  console.log(task.name);          // string | null
  console.log(task.status);        // string | null
  console.log(task.project);       // string | null
}

エラーハンドリング

SDK は型付きエラーをスローするため、異なるエラーモードを正確に処理できます。

import Avala, { AvalaError, NotFoundError, RateLimitError } from "@avala-ai/sdk";

const avala = new Avala();

try {
  const dataset = await avala.datasets.get("nonexistent");
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log(`Dataset not found: ${error.message}`);
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter} seconds.`);
  } else if (error instanceof AvalaError) {
    console.log(`API error (${error.statusCode}): ${error.message}`);
  } else {
    throw error;
  }
}

例外	説明
`AvalaError`	すべての Avala API エラーの基底エラークラス。
`AuthenticationError`	無効または不足している API キー（HTTP 401）。
`NotFoundError`	リクエストされたリソースが存在しない（HTTP 404）。
`RateLimitError`	API レート制限を超過（HTTP 429）。`retryAfter` プロパティを含みます。
`ValidationError`	リクエストペイロードのバリデーション失敗（HTTP 400/422）。
`ServerError`	サーバーが内部エラーを返した（HTTP 5xx）。

ページネーション

リストメソッドはカーソルベースのページネーション付き CursorPage<T> オブジェクトを返します。

// 現在のページのアイテムにアクセス
const page = await avala.datasets.list({ limit: 10 });
for (const dataset of page.items) {
  console.log(dataset.name);
}

// 次のページを取得
if (page.hasMore) {
  const nextPage = await avala.datasets.list({
    limit: 10,
    cursor: page.nextCursor!,
  });
}

エージェントの操作

エージェントの作成

const agent = await avala.agents.create({
  name: "QA Bot",
  events: ["task.completed"],
  callbackUrl: "https://example.com/webhook",
  taskTypes: ["annotation"],
});

エージェント実行の一覧

const executions = await avala.agents.listExecutions(agent.uid);
for (const exec of executions.items) {
  console.log(`${exec.eventType} — ${exec.status}`);
}

ウェブフックの操作

ウェブフックの作成

const webhook = await avala.webhooks.create({
  targetUrl: "https://example.com/webhook",
  events: ["task.completed", "export.ready"],
});

配信の確認

const deliveries = await avala.webhookDeliveries.list();
for (const d of deliveries.items) {
  console.log(`${d.eventType} — ${d.status} (attempts: ${d.attempts})`);
}

品質とコンセンサスの操作

品質ターゲットの作成

const target = await avala.qualityTargets.create("proj_uid", {
  name: "Accuracy",
  metric: "accuracy",
  operator: "gte",
  threshold: 0.95,
  notifyEmails: ["alerts@example.com"],
});

コンセンサスの確認

const summary = await avala.consensus.getSummary("proj_uid");
console.log(`Mean score: ${summary.meanScore}`);
console.log(`Coverage: ${summary.itemsWithConsensus}/${summary.totalItems}`);

フリート管理

フリート管理はプレビュー版です。ここで説明する API は変更される可能性があります。

fleet ネームスペースは、デバイスレジストリ、レコーディング、イベント、ルール、アラートへのアクセスを提供します。

// List online devices
const devices = await avala.fleet.devices.list({ status: "online" });

// Create a timeline event on a recording
const event = await avala.fleet.events.create({
  recordingId: "rec_abc123",
  timestamp: "2026-01-15T10:30:00Z",
  type: "anomaly",
  label: "Gripper force spike",
  metadata: { force_n: 45.2 },
});

// Create a recording rule
const rule = await avala.fleet.rules.create({
  name: "High Latency Alert",
  condition: { type: "threshold", topic: "/diagnostics/latency", field: "data.value", operator: "gt", value: 100 },
  actions: [{ type: "tag", value: "high-latency" }, { type: "notify", channelId: "ch_your_channel_id" }],
});

完全な例についてはフリートダッシュボードガイドをご覧ください。

設定

初期化時にクライアントの動作をカスタマイズできます。

import Avala from "@avala-ai/sdk";

const avala = new Avala({
  apiKey: "your-api-key",
  baseUrl: "https://api.avala.ai/api/v1", // Default
  timeout: 60_000,    // Request timeout in ms (default: 30000)
});

パラメータ	型	デフォルト	説明
`apiKey`	`string`	`AVALA_API_KEY` 環境変数	Avala API キー。
`baseUrl`	`string`	`https://api.avala.ai/api/v1`	API ベース URL。
`timeout`	`number`	`30000`	リクエストタイムアウト（ミリ秒）。

ゼロ依存

@avala-ai/sdk パッケージはランタイム依存がゼロです。Node.js 18+、Deno、Bun で利用可能なネイティブ fetch API を使用します。

フレームワークの例

Next.js (App Router)

// app/api/datasets/route.ts
import Avala from "@avala-ai/sdk";
import { NextResponse } from "next/server";

const avala = new Avala({ apiKey: process.env.AVALA_API_KEY! });

export async function GET() {
  const datasets = await avala.datasets.list();
  return NextResponse.json(datasets);
}

Express

import express from "express";
import Avala from "@avala-ai/sdk";

const app = express();
const avala = new Avala(); // Reads AVALA_API_KEY from env

app.get("/datasets", async (req, res) => {
  try {
    const datasets = await avala.datasets.list();
    res.json(datasets);
  } catch (error) {
    res.status(500).json({ error: "Failed to fetch datasets" });
  }
});

app.listen(3000, () => {
  console.log("Server running on port 3000");
});

​インストール

​クイックスタート

​アカウントの作成

​認証

​データセットの操作

​データセットの一覧表示

​データセットの取得

​プロジェクトの操作

​プロジェクトの一覧表示

​プロジェクトの取得

​タスクの操作

​タスクの一覧表示

​タスクの取得

​エクスポートの操作

​エクスポートの作成

​完了のポーリング

​TypeScript 型

​エラーハンドリング

​ページネーション

​エージェントの操作

​エージェントの作成

​エージェント実行の一覧

​ウェブフックの操作

​ウェブフックの作成

​配信の確認

​品質とコンセンサスの操作

​品質ターゲットの作成

​コンセンサスの確認

​フリート管理

​設定

​ゼロ依存

​フレームワークの例

​Next.js (App Router)

​Express

インストール

クイックスタート

アカウントの作成

認証

データセットの操作

データセットの一覧表示

データセットの取得

プロジェクトの操作

プロジェクトの一覧表示

プロジェクトの取得

タスクの操作

タスクの一覧表示

タスクの取得

エクスポートの操作

エクスポートの作成

完了のポーリング

TypeScript 型

エラーハンドリング

ページネーション

エージェントの操作

エージェントの作成

エージェント実行の一覧

ウェブフックの操作

ウェブフックの作成

配信の確認

品質とコンセンサスの操作

品質ターゲットの作成

コンセンサスの確認

フリート管理

設定

ゼロ依存

フレームワークの例

Next.js (App Router)

Express