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.

bash

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:

bash

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).

bash

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.

bash

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.

bash

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/...).

bash

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

Stop polling on terminal states:

• COMPLETED
• FAILED
• CANCELED

Recommended helper:

bash

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:

• 400: request format issue
• 401: missing/invalid API key
• 402: possible payment/credits issue in runtime
• 404: endpoint or generation id not found
• 422: schema validation failed

Classify non-2xx runtime errors with:

bash

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:

• Open https://skills.video/dashboard and go to Billing/Credits
• Recharge or purchase additional credits
• Retry after recharge

Optional balance check:

bash

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#

• scripts/ensure_api_key.py: validate SKILLS_VIDEO_API_KEY and show first-run setup guidance
• scripts/handle_runtime_error.py: classify runtime errors and provide recharge guidance for insufficient credits
• scripts/inspect_openapi.py: extract SSE/polling endpoint pair, contract, and payload template
• scripts/create_and_wait.py: create via SSE and auto-fallback to polling when stream does not reach terminal status
• scripts/wait_generation.py: poll generation status until terminal completion and return final response
• references/open-platform-api.md: SSE-first lifecycle, fallback polling, retry baseline
• references/image-model-endpoints.md: current image endpoint snapshot from docs.json