AI Text Reference

Use the AI text hooks to build chat interfaces, stream prose, and generate structured JSON data. All hooks handle errors automatically and return undefined instead of throwing when a request fails.

Choosing a Hook

• useAIChat builds multi-turn conversations. It manages a message array and streams assistant responses into that array.
• useAIText generates one streaming text value for stories, summaries, explanations, and other single-turn prose.
• useAIObject generates structured data that matches a JSON schema. It does not stream partial objects.

Import the hooks from the shared AI hook module:

import { useAIText } from "@/hooks/use-ai";
import { usePersistentItem } from "@/hooks/use-persistent-item";

export default function App() {
  const [story, setStory] = usePersistentItem("story", "");
  const { textStream, setTextStream, generateText, isLoading, error } =
    useAIText({ initialText: story });

  const handleGenerate = async () => {
    const result = await generateText({
      prompt: "Write a short story about a cat",
      systemPrompt: "You are a creative storyteller.",
    });

    if (result) setStory(result);
  };

  return (
    <div>
      <button onClick={handleGenerate} disabled={isLoading}>
        Generate story
      </button>
      <button onClick={() => setTextStream("")}>Clear</button>
      {error && <p className="text-destructive">{error.message}</p>}
      <div>{textStream}</div>
    </div>
  );
}

Render textStream directly for responsive streaming UI, then use the resolved promise value for persistence or final processing.

useAIObject

useAIObject returns structured JSON data matching a schema.

const { generateObject, isLoading, error, clearError } = useAIObject(options);

Options:

• systemPrompt (string, default ""): Default instruction for all requests.
• enableWebSearch (boolean, default false): Default web-search setting.
• onError ((error: Error) => void): Custom error handler.
• onFinish ((object: T) => void): Called with the generated object.

generateObject<T>(options) requires:

• prompt (string): Description of the object to generate.
• schema (object): JSON Schema for the output.

It also accepts systemPrompt, enableWebSearch, context, attachments, and model, and returns Promise<T | undefined>.

Schemas must follow the structured-output subset:

• The root type must be "object".
• Every object must set "additionalProperties": false.
• Every property must be listed in required; optional fields are not supported.
• Supported types are "string", "number", "integer", "boolean", "object", and "array".
• enum values must be strings.

import { useAIObject } from "@/hooks/use-ai";
import { usePersistentItem } from "@/hooks/use-persistent-item";

type Plan = {
  title: string;
  tasks: string[];
  priority: "low" | "medium" | "high";
};

export default function App() {
  const [plan, setPlan] = usePersistentItem<Plan | null>("plan", null);
  const { generateObject, isLoading, error } = useAIObject();

  const handleGeneratePlan = async (goal: string) => {
    const result = await generateObject<Plan>({
      prompt: `Generate a plan for: ${goal}`,
      schema: {
        type: "object",
        properties: {
          title: { type: "string" },
          tasks: { type: "array", items: { type: "string" } },
          priority: { type: "string", enum: ["low", "medium", "high"] },
        },
        required: ["title", "tasks", "priority"],
        additionalProperties: false,
      },
    });

    if (result) setPlan(result);
  };

  return (
    <div>
      {isLoading && <p>Generating...</p>}
      {error && <p className="text-destructive">{error.message}</p>}
      {plan && <pre>{JSON.stringify(plan, null, 2)}</pre>}
    </div>
  );
}

Attachments and Web Search

All three text hooks accept attachments in per-request options. Use files directly from local inputs, uploaded file URLs, or YouTube URLs:

await generateText({
  prompt: "Summarize this video",
  attachments: [{ url: youtubeUrl }],
});

await generateObject({
  prompt: "Extract the receipt details",
  schema: receiptSchema,
  attachments: [receiptImageFile],
});

Set enableWebSearch: true for prompts that need current information, such as weather, news, or live facts.

Model Selection

When no model is specified, the platform chooses the best available model for the user's subscription tier. To expose model choice, pass a model ID and build selectors from listTextModels():

import { listTextModels, useAIText } from "@/hooks/use-ai";

const models = listTextModels();
const [modelId, setModelId] = React.useState<string | undefined>(undefined);
const { generateText } = useAIText();

await generateText({
  prompt: "Summarize this article",
  model: modelId,
});

listTextModels() returns ModelInfo[] with:

• id: Model ID to pass as model.
• displayName: Human-readable display name.
• provider: Provider name.
• tier: "lite", "standard", or "advanced".
• description: Short model description.
• capabilities: Capability strings such as web_search, image_input, file_input, audio_input, and video_input.

Advanced models require a Pro subscription. Deprecated models automatically fall back to a recommended replacement.

Best Practices

• Render streamed state (messages or textStream) directly so the UI updates as tokens arrive.
• Persist final promise results, not partial streaming state.
• Restore user input on failure if you clear it optimistically.
• Use setMessages and setTextStream for local resets without making API calls.
• Include clear instructions when using attachments so the model knows how to use each file or URL.
• Keep object schemas small and explicit, and include additionalProperties: false on every object.