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:

• Open https://skills.video/dashboard/developer and log in
• Click Create API Key
• Export the key as SKILLS_VIDEO_API_KEY

Example:

export SKILLS_VIDEO_API_KEY="<YOUR_API_KEY>"

1) Identify the spec

Load the most specific OpenAPI first.

• Prefer model-specific OpenAPI when available (for example /v1/openapi.json under a model namespace).
• Fall back to platform-level openapi.json.
• Use references/open-platform-api.md for base URL, auth, and async lifecycle.

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.