cowart-image-gen

name	cowart-image-gen
description	Generate a final AI bitmap into the selected Cowart "AI 图片" holder, sized to the holder ratio so it needs no cropping, including any requested in-image text by default. Use when the user asks Codex to create, fill, replace, or place an AI-generated image inside the currently selected AI image placeholder on a Cowart canvas.

Cowart Image Gen

Use this skill when the selected Cowart canvas shape is an AI 图片 holder created by the Cowart toolbar.

Preconditions

The Cowart service should be running for the user's active project, usually at:

http://127.0.0.1:43217

New holders are tldraw frame shapes with:

{
  "type": "frame",
  "meta": {
    "cowartAiImageHolder": true
  }
}

Older canvases may still contain legacy geo rectangle holders with the same meta flag. Support both shapes.

Preferred workflow: generate_cowart_image MCP tool

When a Cowart image provider is configured, prefer the Cowart MCP generate_cowart_image tool. It is the simplest and most reliable path and it solves image sizing for you:

• It reads the selected AI 图片 holder (or the holderShapeId you pass).
• It computes a generation size that matches the holder aspect ratio under the provider's constraints (sides multiple of 16, total pixels within range), so the result needs no cropping and no distortion.
• It calls the configured OpenAI-compatible image API, saves the bitmap into the page-local assets folder, and places the result at the holder's spot. By default it replaces the AI 图片 frame with a standalone image (so the user can move and resize it freely); pass keepHolder: true only if the user wants to keep the frame and put the image inside it.

A provider key is required in the local environment, usually COWART_IMAGE_API_KEY (also accepts GAISC_API_KEY / OPENAI_API_KEY). Base URL and model can be set with COWART_IMAGE_BASE_URL and COWART_IMAGE_MODEL.

Steps:

1. Confirm exactly one selected shape is an AI 图片 holder (either isAiImageHolder: true or meta.cowartAiImageHolder: true). If not, ask the user to select one. You may read the selection with:

   curl -s http://127.0.0.1:43217/api/selection
   

   or the Cowart MCP get_cowart_selection tool.

2. Call generate_cowart_image with the prompt:

   {
     "prompt": "<image prompt>",
     "projectDir": "/absolute/path/to/user/codex-project",
     "cowartUrl": "http://127.0.0.1:43217"
   }
   

   • If the asset needs visible copy, labels, poster text, ad text, UI text, or typography, include that text directly in the prompt and let the image model render it. Do not generate a text-free background and then add text locally unless the user explicitly asks for deterministic local typography, SVG/vector output, or another non-generation layout step.
   • Do not crop, pad, or resize the bitmap locally to fit the holder. The tool already matches the holder ratio. Never run a local Pillow/ImageMagick crop step for fitting.
   • Optional: model, size (explicit WIDTHxHEIGHT override), targetPx (output resolution budget), holderShapeId, snapHolder (defaults true), fileName, altText.

3. Confirm the returned shapeId, holderId, requestedSize, and saved assetFile, then let the browser hot-reload.

Fallback workflow: built-in image generation

Only when no provider is configured, the provider key is missing, or generate_cowart_image is unavailable, fall back to the built-in imagegen skill:

1. Use the selected holder's props.w and props.h as the size contract and generate an image as close to that aspect ratio as the built-in model allows.

2. Copy the selected generated image from $CODEX_HOME/generated_images/... into the selected page's asset folder:

   canvas/pages/<page-id-without-page-prefix>/assets/
   

3. Insert it with the Cowart MCP insert_cowart_image tool using fit: "cover" so the image fills the holder without distortion (the tool applies a non-destructive tldraw crop; it does not edit the source pixels):

   • For a frame holder, insert the image as a child of the frame (parentId = holder id, x = 0, y = 0, props.w/props.h = holder).
   • For a legacy geo rectangle holder, keep the same x, y, rotation, parentId, props.w, and props.h as the holder.
   • Set meta.cowartGeneratedForAiImageHolder to the holder shape id.

4. Prefer page-local asset URLs in the image asset:

   /page-assets/<page-id-without-page-prefix>/<filename>
   

Notes

• By default generate_cowart_image replaces the AI 图片 frame with the generated standalone image. The result carries meta.cowartGeneratedImage and meta.cowartGeneratedForAiImageHolder, so to regenerate you can select that generated image and ask again. Pass keepHolder: true if the frame must stay.
• If there is already a generated image and the user says "替换", remove or update that generated image shape instead of stacking a new copy on top.
• Never overwrite an existing asset file without an explicit replace request; use a timestamped filename.