stitch-sdk-usage

Stitch SDK の使用

Stitch SDK は、AI を活用した UI 生成サービスである Google Stitch 用の TypeScript インターフェースを提供します。

インストール

npm install @google/stitch-sdk

環境変数

export STITCH_API_KEY="your-api-key"

クイックスタート

import { stitch } from "@google/stitch-sdk";

const project = await stitch.createProject({ title: "My App" });
const generation = await project.generate("A settings page with dark theme");
const screen = generation.first; // all screens: generation.screens
const html = await screen.getHtml(); // the HTML content
const png = await screen.getImage(); // screenshot bytes (Uint8Array)

stitch シングルトンは環境変数から STITCH_API_KEY を読み込み、初回使用時に接続します。セットアップコードは必要ありません。

プロジェクトの操作

import { stitch } from "@google/stitch-sdk";

// List all projects
const projects = await stitch.projects();

// Reference a project by ID (no network call)
const project = stitch.project("4044680601076201931");

// Create a new project
const newProject = await stitch.createProject({ title: "My App" });

デザインシステム

// Create a design system for a project
const ds = await project.createDesignSystem({ displayName: "My Theme" });

// List design systems
const systems = await project.listDesignSystems();

// Reference by ID (no network call)
const dsRef = project.designSystem("existing-asset-id");

// Update a design system
const updated = await ds.update({ displayName: "Updated Theme" });

// Apply to screens (requires SelectedScreenInstance objects from project.data.screenInstances)
// Returns a Generation — all updated screens are in .screens
const applied = await ds.apply([
  { id: "instance-id", sourceScreen: "projects/123/screens/456" },
]);
applied.screens;

画像のアップロード

既存の画像ファイル（PNG、JPG、JPEG、WEBP）をアップロードして、モックアップやアセットから直接画面を作成します。

import { stitch } from "@google/stitch-sdk";

const project = stitch.project("your-project-id");

// Upload a local image file
const [screen] = await project.upload("./mockup.png", {
  title: "Home Screen",
});

console.log(screen.id);
const html = await screen.getHtml(); // HTML content
const png = await screen.getImage(); // screenshot bytes (Uint8Array)

このメソッドはディスクからファイルを読み込み、Stitch REST API に直接送信します。エージェント経由の MCP 呼び出しとは異なり、出力トークンの制限は適用されません。

対応形式： .png、.jpg、.jpeg、.webp

オプション：

オプション	型	デフォルト	説明
title	string	—	作成した画面の表示タイトル
createScreenInstances	boolean	true	画面をキャンバスに追加するかどうか

スローされる例外： StitchError（コード：NOT_FOUND（ファイルが見つからない）、UNKNOWN_ERROR（対応していない形式またはアップロード失敗）、AUTH_FAILED（API キーが無効））

画面の生成と反復

// Generate screens from a prompt. Stitch can return MANY screens per
// generation — a Generation carries all of them plus the raw response.
const generation = await project.generate(
  "Login page with email and password fields",
);
generation.screens; // every generated Screen
generation.first; // convenience: the first screen
generation.raw; // full typed tool response

// Optional settings go in a trailing options object
const mobile = await project.generate("A settings page", {
  deviceType: "MOBILE",
});

// Edit an existing screen (also returns a Generation)
const edited = await generation.first.edit(
  "Make the background dark and add a subtitle",
);

// Generate variants of a screen
const variants = await generation.first.variants(
  "Try different color schemes",
  {
    variantCount: 2,
    creativeRange: "EXPLORE",
    aspects: ["COLOR_SCHEME", "LAYOUT"],
  },
);
variants.screens; // all variant Screens

画面アセットの取得

// CONTENT (fetched for you)
const html = await screen.getHtml(); // HTML string
const png = await screen.getImage(); // Uint8Array

// Or just the signed download URLs
const htmlUrl = await screen.getHtmlUrl();
const imageUrl = await screen.getImageUrl();

URL アクセサーは、利用可能な場合、生成レスポンスのキャッシュ済みデータを使用し、取得したレスポンスをキャッシュに書き戻します。アーティファクトが見つからない場合は、コード NOT_FOUND の StitchError をスローします（空の文字列を黙って返すことはありません）。

動的ツールクライアント（エージェント向け）

JSON ペイロードを MCP ツールに転送するエージェントやオーケストレーションスクリプト向けです。

import { stitch } from "@google/stitch-sdk";

// Find available tools
const { tools } = await stitch.listTools();
for (const tool of tools) {
  console.log(`${tool.name}: ${tool.description}`);
}
// Call a tool with a JSON payload
const result = await stitch.callTool("generate_screen_from_text", {
  projectId: "123",
  prompt: "A login page",
});
await stitch.close();

エラー処理

SDK のすべてのメソッドは、失敗時に StitchError をスローします。try/catch を使用してください。

import { stitch, StitchError } from "@google/stitch-sdk";

try {
  const project = stitch.project("bad-id");
  await project.screens();
} catch (e) {
  if (e instanceof StitchError) {
    console.log(e.code); // "AUTH_FAILED", "NOT_FOUND", etc.
    console.log(e.message); // Human-readable description
    console.log(e.recoverable); // Whether retrying might succeed
  }
}

エラーコード：AUTH_FAILED、NOT_FOUND、PERMISSION_DENIED、RATE_LIMITED、NETWORK_ERROR、VALIDATION_ERROR、CLARIFICATION_REQUIRED、UNKNOWN_ERROR

CLARIFICATION_REQUIRED は回復可能です。generate()／edit()／variants() が画面ではなく質問を返した場合に発生します。e.clarification.question／e.clarification.suggestions を確認し、回答するプロンプトを指定して同じメソッドを再度呼び出してください。

API リファレンス

Stitch クラス

メソッド	戻り値	説明
createProject(options?)	Promise<Project>	新しいプロジェクトを作成（options.title）
projects()	Promise<Project[]>	すべてのプロジェクトを一覧表示
project(id)	Project	ID でプロジェクトを参照（ネットワーク呼び出しなし）

Project クラス

メソッド	戻り値	説明
generate(prompt, options?)	Promise<Generation<Screen>>	画面を生成します — .screens、.first、.raw（options.deviceType、options.modelId）
screens()	Promise<Screen[]>	プロジェクト内のすべての画面を一覧表示します
getScreen(screenId)	Promise<Screen>	ID を指定して特定の画面を取得します
upload(filePath, opts?)	Promise<Screen[]>	画像／HTML ファイルをアップロードし、そこから画面を作成します
createDesignSystem(designSystem)	Promise<DesignSystem>	このプロジェクトのデザインシステムを作成します
listDesignSystems()	Promise<DesignSystem[]>	すべてのデザインシステムを一覧表示します
designSystem(id)	DesignSystem	ID で参照します（API 呼び出しはありません）

deviceType: "MOBILE" | "DESKTOP" | "TABLET" | "AGNOSTIC"

upload の対応形式：.png .jpg .jpeg .webp .html

DesignSystem クラス

メソッド	戻り値	説明
update(designSystem)	Promise<DesignSystem>	デザインシステムのテーマを更新します
apply(selectedScreenInstances)	Promise<Generation<Screen>>	このデザインシステムを画面に適用します（.screens）

Screen クラス

メソッド	戻り値	説明
getHtml()	Promise<string>	画面の HTML コンテンツを取得します
getImage()	Promise<Uint8Array>	スクリーンショットのバイト列を取得します
getHtmlUrl() / getImageUrl()	Promise<string>	署名付きダウンロード URL（キャッシュ対応）
edit(prompt, options?)	Promise<Generation<Screen>>	テキストプロンプトを使用して画面を編集します
variants(prompt, variantOptions, options?)	Promise<Generation<Screen>>	画面のバリエーションを生成します

modelId: "GEMINI_3_8_FLASH" | "GEMINI_3_5_FLASH_LITE"（任意。省略時はバックエンドのデフォルト）

StitchToolClient（エージェント向け）

メソッド	戻り値	説明
callTool(name, args)	Promise<T>	名前を指定して任意の MCP ツールを呼び出します
listTools()	Promise<Tools>	利用可能なツールを確認します
connect()	Promise<void>	MCP 接続を確立します（callTool によって自動的に呼び出されます）
close()	Promise<void>	接続を閉じます

明示的な設定

import { Stitch, StitchToolClient } from "@google/stitch-sdk";

const client = new StitchToolClient({
  apiKey: "your-api-key",
  baseUrl: "https://stitch.googleapis.com/mcp",
  timeout: 300_000,
});

const sdk = new Stitch(client);
const projects = await sdk.projects();

オプション	環境変数	説明
apiKey	STITCH_API_KEY	認証用の API キー
accessToken	STITCH_ACCESS_TOKEN	OAuth アクセストークン
projectId	GOOGLE_CLOUD_PROJECT	GCP プロジェクト ID（OAuth では必須）
baseUrl	—	MCP サーバーの URL（デフォルト：https://stitch.googleapis.com/mcp）
timeout	—	リクエストのタイムアウト（ミリ秒、デフォルト：300000）