ai-image-skills

---

name: "ai-image-skills"

description: Build and execute skills.video image generation REST requests from OpenAPI specs. Use when user needs to create, debug, or document image generation calls on open.skills.video.

---

# ai-image-skills

Overview

Use this skill to turn OpenAPI definitions into working image-generation API calls for `skills.video`.

Prefer deterministic extraction from `openapi.json` instead of guessing fields.

Workflow

1. Check API key and bootstrap environment on first use.

2. Identify the active spec.

3. Select the SSE endpoint pair for an image model.

4. Extract request schema and generate a payload template.

5. Execute `POST /generation/sse/...` as default and keep the stream open.

6. If SSE does not reach terminal completion, poll `GET /generation/{id}` to terminal status.

7. Return only terminal result (`COMPLETED`/`SUCCEEDED`/`FAILED`/`CANCELED`), never `IN_PROGRESS`.

8. Apply retry and failure handling.

0) Check API key (first run)

Run this check before any API call.

python scripts/ensure_api_key.py

If `ok` is `false`, tell the user to:

Example:

export SKILLS_VIDEO_API_KEY="<YOUR_API_KEY>"

1) Identify the spec

Load the most specific OpenAPI first.

2) Select an image endpoint

If `docs.json` exists, derive image endpoints from the `Images` navigation group.

Use `default_endpoints` from the script output as the primary list (SSE first).

python scripts/inspect_openapi.py \
  --openapi /abs/path/to/openapi.json \
  --docs /abs/path/to/docs.json \
  --list-endpoints

When `docs.json` is unavailable, pass a known endpoint directly (for example `/generation/sse/google/nano-banana-pro`).

Use `references/image-model-endpoints.md` as a snapshot list.

3) Extract schema and build payload

Inspect endpoint details and generate a request template from required/default fields.

python scripts/inspect_openapi.py \
  --openapi /abs/path/to/openapi.json \
  --endpoint /generation/sse/google/nano-banana-pro \
  --include-template

Use the returned `request_template` as the starting point.

Do not add fields not defined by the endpoint schema.

Use `default_create_endpoint` from output unless an explicit override is required.

4) Execute SSE request (default) with automatic fallback

Prefer the helper script. It creates via SSE and keeps streaming; if stream ends before terminal completion, it automatically switches to polling fallback.

python scripts/create_and_wait.py \
  --sse-endpoint /generation/sse/google/nano-banana-pro \
  --payload '{"prompt":"Minimal product photo of a matte black coffee grinder on white background"}' \
  --poll-timeout 900 \
  --poll-interval 3

Treat SSE as the default result channel.

Do not finish the task on `IN_QUEUE` or `IN_PROGRESS`.

Return only after terminal result.

5) Fall back to polling

Use polling only if SSE cannot be established, disconnects early, or does not reach a terminal state.

Use `GET /generation/{id}` (or model-spec equivalent path if the OpenAPI uses `/v1/...`).

curl -X GET "https://open.skills.video/api/v1/generation/<GENERATION_ID>" \
  -H "Authorization: Bearer $SKILLS_VIDEO_API_KEY"

Stop polling on terminal states:

Recommended helper:

python scripts/wait_generation.py \
  --generation-id <GENERATION_ID> \
  --timeout 900 \
  --interval 3

Return to user only after helper emits `event=terminal`.

6) Handle errors and retries

Handle these response codes for create, SSE, and fallback poll operations:

Classify non-2xx runtime errors with:

python scripts/handle_runtime_error.py \
  --status <HTTP_STATUS> \
  --body '<RAW_ERROR_BODY_JSON_OR_TEXT>'

If category is `insufficient_credits`, tell the user to recharge:

Optional balance check:

curl -X GET "https://open.skills.video/api/v1/credits" \
  -H "Authorization: Bearer $SKILLS_VIDEO_API_KEY"

Apply retries only for transient conditions (network failure or temporary `5xx`).

Use bounded exponential backoff (for example `1s`, `2s`, `4s`, max `16s`, then fail).

Do not retry unchanged payloads after `4xx` validation errors.

Rate limits and timeouts

Treat rate limits and server-side timeout windows as unknown unless documented in the active OpenAPI or product docs.

If unknown, explicitly note this in output and choose conservative client defaults.

Resources