image-generation
Generate images from text prompts or input images using an async API. Use this skill whenever the user wants to create, generate, or edit images — including text-to-image, image-to-image style transfe
SKILL.mdresources/migrated/v1-skills/image-generation/SKILL.md
GitHubImage Generation (Advanced Version)
Capability Overview
This skill drives an asynchronous image-generation service that supports three modes:
| Mode | Description |
|---|---|
| Text-to-Image | Generate an image from a text prompt alone |
| Image-to-Image | Upload one image + a text instruction (e.g. style transfer, background swap) |
| Multi-Image-to-Image | Compose two or more images together guided by a text prompt |
The workflow is always submit → poll → result. Tasks typically take up to 10 minutes; poll every 5–10 seconds.
Read
references/submit-api.mdfor the full submit endpoint spec. Readreferences/query-api.mdfor the full query/poll endpoint spec.
End-to-End Async Workflow
// Full async workflow: submit → poll → result
async function generateAndWait(
contents: ContentPart[]
): Promise<string> { // returns the raw markdown image text
const { taskId } = await submitTask(contents);
const POLL_INTERVAL_MS = 7000; // 5–10 s recommended
const TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
const deadline = Date.now() + TIMEOUT_MS;
while (Date.now() < deadline) {
await new Promise(r => setTimeout(r, POLL_INTERVAL_MS));
const result = await queryTask(taskId);
if (result.status === "SUCCESS") {
// result.result.candidates[0].content.parts[0].text contains
// the image as a Markdown string: 
return result.result.candidates[0].content.parts[0].text;
}
if (result.status === "FAILED") {
throw new Error(`Task failed: ${JSON.stringify(result.error)}`);
}
if (result.status === "TIMEOUT") {
throw new Error(`Task ${taskId} timed out on the server side`);
}
// PENDING → keep polling
}
throw new Error(`Task ${taskId} timed out after 10 minutes`);
}
Generation-Time Usage (Agent Direct Call)
Use the built-in scripts for generation-time calls. The scripts read INTEGRATIONS_API_KEY from the environment, submit the task, poll until it finishes, extract the Base64 image embedded in the Markdown result, and save it to disk.
The Bash tool timeout MUST be set to 600000ms (600 seconds).
Submit + poll (all-in-one):
# Text-to-image
python3 <skill-path>/scripts/generate_image.py \
--prompt "A cute orange kitten in a sunny garden, cartoon style" \
--output /tmp/generated-image.jpg
# Image-to-image / multi-image composition (repeat --image)
python3 <skill-path>/scripts/generate_image.py \
--prompt "Convert to cartoon illustration style" \
--image /path/to/photo.png \
--output /tmp/generated-image.jpg
Resume polling an existing task:
python3 <skill-path>/scripts/query_image.py --task-id "<task_id>" --output /tmp/generated-image.jpg
The scripts print one JSON line:
- On success:
{"status":"succeed","task_id":"...","file":"/tmp/generated-image.jpg"} - If still processing:
{"status":"processing","task_id":"..."}
On failure they print an error to stderr and exit with a non-zero code.
Note: The Base64 image data exists only in the current response. The script saves it to
--outputimmediately — always pass--output.
Post-Generation Usage (In-App via Edge Function)
See references/submit-api.md for the submit Edge Function boilerplate and references/query-api.md for the query Edge Function boilerplate.
The recommended application-side pattern is:
- Frontend calls the
image-generation-submitEdge Function → receivestaskId - Frontend polls the
image-generation-queryEdge Function every 7 seconds - On
SUCCESS, the Edge Function decodes the Base64 and uploads to Supabase Storage, returning a persistentpublicUrl - Frontend displays the image from
publicUrl
Note
Each complete generation (submit + poll to terminal state) is billed as 1 call. Avoid resubmitting the same task.
Notes
- Key security:
INTEGRATIONS_API_KEYmay only be read server-side in an Edge Function; never expose it to the frontend. - Error handling: Always handle 429 (quota exceeded) and 402 (insufficient balance); forward those error bodies verbatim to the frontend.
- Base64 format: When uploading images,
inline_data.datamust be a pure Base64 string — do not include thedata:image/xxx;base64,prefix. - Request size: The total size of a single request (including all images) must not exceed 20 MB.
- Supported formats: PNG, JPEG, WEBP.
- Timeout: Set the task timeout to at least 10 minutes; poll every 5–10 seconds.