> ## Documentation Index
> Fetch the complete documentation index at: https://giselle.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Giselle SDK

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

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

## 概要

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

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

## インストール

Giselle SDKは npm の [@giselles-ai/sdk](https://www.npmjs.com/package/@giselles-ai/sdk) で公開されています。

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

```bash theme={null}
npm install @giselles-ai/sdk
```

```bash theme={null}
yarn add @giselles-ai/sdk
```

```bash theme={null}
pnpm add @giselles-ai/sdk
```

## クイックスタート

```typescript theme={null}
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); // 出力結果の配列
```

## 設定

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

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

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

### 環境変数

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

```bash theme={null}
# .env
GISELLE_API_KEY=gsk_your_api_key_here
```

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

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

## APIリファレンス

### `client.apps.run()`

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

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

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

**パラメータ:**

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

**戻り値:**

```typescript theme={null}
{
  taskId: string; // 作成されたタスクのID
}
```

### `client.apps.runAndWait()`

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

```typescript theme={null}
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](https://standardschema.dev/) 互換。End Node に JSON（構造化出力）が設定されている場合のみ適用。 |

**戻り値:**

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

**Raw（passthrough）の場合:**

```typescript theme={null}
{
  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）の場合:**

```typescript theme={null}
{
  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から取得することです：

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

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

## エラーハンドリング

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

```typescript theme={null}
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` によるバリデーションに失敗した |

## 使用例

### 基本的な使用方法

```typescript theme={null}
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](https://standardschema.dev/) 互換のスキーマを渡すと、出力が自動的にバリデーションされ、型推論も効くようになります。

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

```typescript theme={null}
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}`);
}
```

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

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

### Fire and Forget（非同期実行）

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

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

### Express.js統合

```typescript theme={null}
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キーを作成](https://giselle.mintlify.site/ja/guides/api/api-keys.md) する
* 統合する前に [Playground](https://giselle.mintlify.site/ja/guides/playground.md) でアプリをテストする
* アプリとワークフローの例については [Cookbooks](https://giselle.mintlify.site/ja/cookbooks/overview.md) をご覧ください


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.