AI Image Reference

Use the AI image hooks to generate new images from prompts or edit existing images. Generated and edited images are returned as PNG data with a hosted URL for display and persistence.

Choosing a Hook

• useAIImage creates new images from a prompt. Reference images can guide style or subject consistency, but the output is a new creative asset.
• useAIImageEdit transforms a source image. The source image is the base image that should be preserved and changed.

Import both hooks from the AI hook module:

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

export default function App() {
  const [prompt, setPrompt] = React.useState("");
  const [sourceUrl] = usePersistentItem<string | null>("sourceUrl", null);
  const [editedUrl, setEditedUrl] = usePersistentItem<string | null>(
    "editedUrl",
    null
  );
  const { editImage, isLoading, error } = useAIImageEdit();

  const handleEdit = async () => {
    if (!prompt.trim() || !sourceUrl) return;

    const images = await editImage({
      prompt: `${prompt.trim()} Keep everything else exactly the same.`,
      image: { url: sourceUrl },
    });

    if (images?.[0]?.url) {
      setEditedUrl(images[0].url);
    }
  };

  return (
    <div>
      {sourceUrl && <img src={sourceUrl} alt="Source" className="w-full rounded-lg" />}
      <input
        value={prompt}
        onChange={(event) => setPrompt(event.target.value)}
        placeholder="Describe how to edit the image..."
      />
      <button onClick={handleEdit} disabled={isLoading || !sourceUrl}>
        {isLoading ? <span className="inline-block h-4 w-4 animate-spin rounded-full border-2 border-current border-t-transparent" /> : "Edit image"}
      </button>
      {error && <p className="text-destructive">{error.message}</p>}
      {editedUrl && <img src={editedUrl} alt="Edited" className="w-full rounded-lg" />}
    </div>
  );
}

You can pass a local file directly:

const images = await editImage({
  prompt:
    "Transform this photo into a loose watercolor painting. Preserve the composition and subject placement.",
  image: file,
});

Prompting

Image prompts work best when they describe the scene instead of listing keywords. Include:

• Subject: The main object, person, animal, or scenery.
• Setting: Where the scene takes place.
• Style: Photorealistic, watercolor, flat vector, sticker, 3D render, or another creative direction.
• Lighting and mood: Golden hour, dramatic studio light, cool moonlight, soft ambient light.
• Composition: Close-up, wide shot, aerial view, negative space, or camera angle.
• Details and textures: Fine details that make the output specific.

For edits, say exactly what should change and what should stay the same. For targeted edits, name the object precisely: "Change only the blue sofa to a vintage brown leather chesterfield sofa. Keep the rest of the room exactly as it is."

Model Selection

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

import { listImageModels, useAIImage } from "@/hooks/use-ai";

const models = listImageModels();
const [modelId, setModelId] = React.useState<string | undefined>(undefined);
const { generateImage } = useAIImage();

await generateImage({
  prompt: "A sunset over the ocean",
  model: modelId,
});

listImageModels() returns ModelInfo[] with id, displayName, provider, tier, description, and capabilities. Image model capabilities include:

• generation: Supports creating images from a prompt.
• editing: Supports editing or remixing existing images.

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

Best Practices

• Use the url field for display and persistence.
• Do not store base64 with usePersistentItem; it can exceed storage limits.
• Use base64 only for client-side image processing.
• Choose an aspect ratio that matches the final UI or export format.
• Use numImages to create variations from a single prompt.
• Use reference images with useAIImage for subject or style consistency across new images.
• Use useAIImageEdit when the source image itself should remain the base.