Giselle SDK

Giselle SDKを使用して、アプリを外部アプリケーションやサービスと統合する方法を学びます。

この機能は現在 Private Preview です。アクセスは一部のユーザーに限定されています。機能やAPIは予告なく変更される場合があります。

概要

Giselle SDK（@giselles-ai/sdk）は、Node.jsアプリケーションからGiselle APIと対話するためのシンプルで型安全な方法を提供します。認証、リクエストフォーマット、タスク完了のポーリングを自動的に処理します。

SDKはサーバーサイドでの使用専用に設計されています。クライアントサイドのコード（ブラウザ）では使用しないでください。APIキーが露出してしまいます。

インストール

Giselle SDKは npm の @giselles-ai/sdk で公開されています。

お好みのパッケージマネージャーを使用してSDKをインストールします：

npm install @giselles-ai/sdk

yarn add @giselles-ai/sdk

pnpm add @giselles-ai/sdk

クイックスタート

import Giselle from "@giselles-ai/sdk";

// クライアントを初期化
const client = new Giselle({
  apiKey: process.env.GISELLE_API_KEY,
});

// アプリを実行して結果を待つ
const { task } = await client.apps.runAndWait({
  appId: "app_xxxxx",
  input: { text: "こんにちは、Giselle！" },
});

console.log(task.status); // "completed"
console.log(task.outputs); // 出力結果の配列

設定

コンストラクタオプション

const client = new Giselle({
  apiKey: string;       // 必須: APIキー
  baseUrl?: string;     // オプション: APIベースURL（デフォルト: "https://studio.giselles.ai"）
  fetch?: typeof fetch; // オプション: カスタムfetch実装
});

オプション	必須	デフォルト	説明
`apiKey`	はい	-	Giselle APIキー。APIキー設定から取得してください。
`baseUrl`	いいえ	`https://studio.giselles.ai`	APIリクエストのベースURL。
`fetch`	いいえ	グローバル `fetch`	特定のランタイム環境用のカスタムfetch実装。

環境変数

APIキーは環境変数に保存することをお勧めします：

# .env
GISELLE_API_KEY=gsk_your_api_key_here

const client = new Giselle({
  apiKey: process.env.GISELLE_API_KEY,
});

APIキーをバージョン管理にコミットしないでください。環境変数またはシークレットマネージャーを使用してください。

APIリファレンス

`client.apps.run()`

アプリの実行を開始し、タスクIDをすぐに返します。ポーリングを自分で処理したい場合や、結果を待つ必要がない場合に使用します。

const { taskId } = await client.apps.run({
  appId: "app_xxxxx",
  input: { text: "入力テキスト" },
});

console.log(taskId); // "tsk_xxxxx"

パラメータ:

パラメータ	型	必須	説明
`appId`	`string`	はい	実行するアプリのID（形式: `app_xxxxx`）
`input.text`	`string`	はい	アプリへのテキスト入力

戻り値:

{
  taskId: string; // 作成されたタスクのID
}

`client.apps.runAndWait()`

アプリの実行を開始し、タスクが完了するまでポーリングします。ほとんどのユースケースで推奨されるメソッドです。

const { task } = await client.apps.runAndWait({
  appId: "app_xxxxx",
  input: { text: "入力テキスト" },
  pollIntervalMs: 1000,  // オプション: ポーリング間隔（デフォルト: 1000ms）
  timeoutMs: 60000,      // オプション: タイムアウト（デフォルト: 1200000ms / 20分）
});

パラメータ:

パラメータ	型	必須	デフォルト	説明
`appId`	`string`	はい	-	実行するアプリのID
`input.text`	`string`	はい	-	アプリへのテキスト入力
`pollIntervalMs`	`number`	いいえ	`1000`	完了チェックの頻度（ms）
`timeoutMs`	`number`	いいえ	`1200000`	最大待機時間（ms）
`schema`	`StandardSchemaV1`	いいえ	-	出力のバリデーションスキーマ。Standard Schema v1 互換。End Node に JSON（構造化出力）が設定されている場合のみ適用。

戻り値:

End Node の Output Format 設定によって、戻り値の task の型が異なります。

Raw（passthrough）の場合:

{
  task: {
    id: string;
    workspaceId: string;
    name: string;
    status: "completed" | "failed" | "cancelled";
    outputType: "passthrough";
    steps: Array<{
      title: string;
      status: string;
      items: Array<{
        id: string;
        title: string;
        status: string;
        generationId: string;
        outputs?: unknown[];
        error?: string;
      }>;
    }>;
    outputs: Array<{
      title: string;
      generationId: string;
      outputs: unknown[];
    }>;
  };
}

JSON（object）の場合:

{
  task: {
    id: string;
    workspaceId: string;
    name: string;
    status: "completed" | "failed" | "cancelled";
    outputType: "object";
    output: T; // schema を渡した場合はその型、未指定なら Record<string, unknown>
    steps: Array<{
      title: string;
      status: string;
      items: Array<{
        id: string;
        title: string;
        status: string;
        generationId: string;
        outputs?: unknown[];
        error?: string;
      }>;
    }>;
  };
}

App IDとコードスニペットの取得方法

App IDとすぐに使えるコードスニペットを取得する最も簡単な方法は、Workspaceから取得することです：

Workspaceでアプリを開く
右上の Run ボタンをクリック
表示されるダイアログで Code タブを選択
appId が既に埋め込まれた完全なコードスニペットが表示されます。このコードをコピーして、アプリケーションで使用してください。
End Node で JSON（構造化出力）を有効にしている場合、スキーマ定義を含むコードスニペットと、実際に返却される Response の JSON 構造がプレビュー表示されます

App IDの形式は app_ の後に一意の識別子が続きます（例：app_abc123xyz）。

エラーハンドリング

SDKは異なる失敗シナリオに対して特定のエラータイプをスローします：

import Giselle, {
  ConfigurationError,
  ApiError,
  TimeoutError,
  UnsupportedFeatureError,
  SchemaValidationError,
} from "@giselles-ai/sdk";

try {
  const { task } = await client.apps.runAndWait({
    appId: "app_xxxxx",
    input: { text: "こんにちは" },
  });
} catch (error) {
  if (error instanceof ConfigurationError) {
    // 設定が不足または無効（例：APIキーなし）
    console.error("設定エラー:", error.message);
  } else if (error instanceof ApiError) {
    // APIリクエストが失敗
    console.error("APIエラー:", error.status, error.responseText);
  } else if (error instanceof TimeoutError) {
    // タスクがタイムアウト内に完了しなかった
    console.error("タスクタイムアウト:", error.message);
  } else if (error instanceof UnsupportedFeatureError) {
    // サポートされていない機能を使用しようとした
    console.error("サポートされていない機能:", error.message);
  } else if (error instanceof SchemaValidationError) {
    // schema によるバリデーションに失敗
    console.error("スキーマバリデーションエラー:", error.message);
  }
}

エラータイプ

エラータイプ	説明
`ConfigurationError`	設定が不足または無効（例：APIキーが提供されていない）
`ApiError`	APIへのHTTPリクエストが失敗。`status` と `responseText` プロパティを含む。
`TimeoutError`	指定されたタイムアウト内にタスクが完了しなかった
`UnsupportedFeatureError`	まだサポートされていない機能を使用しようとした（例：ファイル入力）
`SchemaValidationError`	`schema` によるバリデーションに失敗した

使用例

基本的な使用方法

import Giselle from "@giselles-ai/sdk";

const client = new Giselle({
  apiKey: process.env.GISELLE_API_KEY,
});

async function runMyApp(userInput: string) {
  const { task } = await client.apps.runAndWait({
    appId: "app_xxxxx",
    input: { text: userInput },
  });

  if (task.status === "completed") {
    return task.outputs;
  } else {
    throw new Error(`タスク失敗: ${task.status}`);
  }
}

構造化出力の受け取り

End Node で JSON（構造化出力）が有効な場合、task.outputType === "object" となり task.output に構造化結果が入ります。
schema パラメータに Standard Schema v1 互換のスキーマを渡すと、出力が自動的にバリデーションされ、型推論も効くようになります。

対応ライブラリ: Zod (3.24+)、Valibot (1.0+)、ArkType (2.0+)、Yup (1.7+)、Effect Schema (3.13+)

import { z } from "zod";

const BlogCardSchema = z.object({
  title: z.string(),
  summary: z.string(),
  tags: z.array(z.string()),
});

async function runMyAppWithStructuredOutput(userInput: string) {
  const { task } = await client.apps.runAndWait({
    appId: "app_xxxxx",
    input: { text: userInput },
    schema: BlogCardSchema,
  });

  if (task.status === "completed" && task.outputType === "object") {
    // task.output は BlogCardSchema の型が推論される
    return task.output;
  }

  throw new Error(`タスク失敗: ${task.status}`);
}

カスタムタイムアウト付き

const { task } = await client.apps.runAndWait({
  appId: "app_xxxxx",
  input: { text: "時間がかかる可能性のある複雑なクエリ" },
  timeoutMs: 300000, // 5分
  pollIntervalMs: 2000, // 2秒ごとにチェック
});

Fire and Forget（非同期実行）

// タスクを開始するが完了を待たない
const { taskId } = await client.apps.run({
  appId: "app_xxxxx",
  input: { text: "バックグラウンド処理" },
});

console.log(`タスク開始: ${taskId}`);
// タスクの状態はAPIまたはGiselleで後から確認できます

Express.js統合

import express from "express";
import Giselle from "@giselles-ai/sdk";

const app = express();
const client = new Giselle({
  apiKey: process.env.GISELLE_API_KEY,
});

app.use(express.json());

app.post("/api/process", async (req, res) => {
  try {
    const { task } = await client.apps.runAndWait({
      appId: "app_xxxxx",
      input: { text: req.body.text },
      timeoutMs: 60000,
    });

    res.json({
      success: true,
      outputs: task.outputs,
    });
  } catch (error) {
    res.status(500).json({
      success: false,
      error: error.message,
    });
  }
});

app.listen(3000);

現在の制限事項

テキスト入力のみ: 現在、テキスト入力のみがサポートされています。ファイル入力は将来のリリースでサポートされる予定です。
サーバーサイドのみ: SDKはAPIキーを保護するため、サーバーサイド環境でのみ使用してください。

次のステップ

始めるために APIキーを作成する
統合する前に Playground でアプリをテストする
アプリとワークフローの例については Cookbooks をご覧ください

このページの内容