english/.opencode/skills/stitch/references/stitch-sdk-api.md

Stitch SDK API Reference

Condensed reference for @google/stitch-sdk. Agent-optimized — covers common operations only.

Installation

npm install @google/stitch-sdk
# Optional: Vercel AI SDK integration
npm install @google/stitch-sdk ai

Authentication

export STITCH_API_KEY="sk_..."  # From https://stitch.withgoogle.com/settings/api

SDK auto-reads STITCH_API_KEY from environment. No explicit config needed.

Core API

Stitch (root singleton)

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

const projects = await stitch.projects();         // List all projects
const project = stitch.project("my-id");          // Get project handle (sync)

Project

const project = stitch.project("project-123");  // sync — returns handle

// Generate screen from prompt (positional params, uppercase device types)
const screen = await project.generate(
  "Login page with email/password",
  "MOBILE"  // optional: "MOBILE" | "DESKTOP" | "TABLET" | "AGNOSTIC"
);

const screens = await project.screens();           // List all screens
const screen = await project.getScreen(screenId);  // Get specific screen

Screen

// Export
const htmlUrl = await screen.getHtml();     // Returns download URL (HTML + Tailwind)
const imageUrl = await screen.getImage();   // Returns download URL (PNG screenshot)

// Edit/refine (positional: prompt, deviceType?, modelId?)
const edited = await screen.edit("Make colors darker, add search bar");

// Generate variants (positional: prompt, variantOptions, deviceType?, modelId?)
const variants = await screen.variants("Different color schemes", {
  variantCount: 3,            // 1-5 variants
  creativeRange: "medium",    // "low" | "medium" | "high"
  aspects: ["COLOR_SCHEME"]   // "COLOR_SCHEME" | "LAYOUT" | etc.
});

StitchToolClient (low-level MCP access)

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

const client = new StitchToolClient({ apiKey: "sk_..." });
const tools = await client.listTools();
const result = await client.callTool("create_project", { title: "My App" });

Vercel AI SDK Integration

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

const { text } = await generateText({
  model: yourModel,
  tools: stitchTools(),
  prompt: "Create a modern dashboard"
});

Type Definitions

type DeviceType = "DEVICE_TYPE_UNSPECIFIED" | "MOBILE" | "DESKTOP" | "TABLET" | "AGNOSTIC";
type ModelId = "MODEL_ID_UNSPECIFIED" | "GEMINI_3_PRO" | "GEMINI_3_FLASH";

interface Stitch {
  projects(): Promise<Project[]>;
  createProject(title?: string): Promise<Project>;
  project(id: string): Project;  // sync — returns handle, no API call
}

interface Project {
  id: string;
  generate(prompt: string, deviceType?: DeviceType, modelId?: ModelId): Promise<Screen>;
  screens(): Promise<Screen[]>;
  getScreen(screenId: string): Promise<Screen>;
}

interface Screen {
  id: string;
  getHtml(): Promise<string>;   // Download URL
  getImage(): Promise<string>;  // Download URL
  edit(prompt: string, deviceType?: DeviceType, modelId?: ModelId): Promise<Screen>;
  variants(prompt: string, variantOptions: any, deviceType?: DeviceType, modelId?: ModelId): Promise<Screen[]>;
}

class StitchError extends Error {
  code: "AUTH_FAILED" | "NOT_FOUND" | "RATE_LIMITED" | string;
}

Error Handling

Code	Meaning	Action
AUTH_FAILED	Bad/missing API key	Check STITCH_API_KEY env var
NOT_FOUND	Screen/project doesn't exist	Verify ID
RATE_LIMITED	Daily quota exceeded	Wait until midnight UTC or use fallback

try {
  const screen = await project.generate(prompt);
} catch (error) {
  if (error.code === "RATE_LIMITED") {
    console.error("Quota exceeded — use ck:ui-ux-pro-max fallback");
  }
}