Ai Image Skills

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

Security Scan

The skill generally does what it claims (builds and runs skills.video image-generation calls), but its metadata and runtime instructions are inconsistent: the code requires an API key (SKILLS_VIDEO_API_KEY) and performs network calls, yet the registry metadata does not declare any required environment variables—this mismatch and a few small implementation choices warrant caution.

Purpose & Capability

The skill's name/description (image-generation for open.skills.video) aligns with included scripts that inspect OpenAPI, create SSE requests, and poll results. However, the registry metadata declares no required environment variables or primary credential even though the runtime relies on SKILLS_VIDEO_API_KEY for authenticated calls. This is an internal inconsistency (likely an omission) and reduces transparency.

Instruction Scope

SKILL.md instructs the agent to read OpenAPI/docs JSON files, build payloads from schema, open SSE streams to skills.video endpoints, and fall back to polling. The scripts read only user-specified OpenAPI/docs files and use the SKILLS_VIDEO_API_KEY for network requests; they do not attempt to read other system-wide secrets or unrelated paths. The scope of actions in the instructions is consistent with the stated purpose.

Install Mechanism

There is no install spec (instruction-only install), and the package includes only local Python scripts and docs. No remote downloads or archive extraction are performed. This is low-risk from an installation perspective.

Credentials

The code and instructions require an API key (SKILLS_VIDEO_API_KEY) to call https://open.skills.video/api/v1, but the registry metadata lists no required env vars or primary credential. Requesting a bearer API key is proportionate for this service, but the metadata omission is a transparency/consistency problem. Also note the scripts will use whatever value is in SKILLS_VIDEO_API_KEY (if present) when making network calls; do not set a credential you don't trust being used for these endpoints. No other unrelated secrets are requested by the code.

Persistence & Privilege

The skill does not request permanent/always inclusion (always:false) and does not modify other skills or global agent settings. It runs scripts on demand and relies on environment variables and local files, which is appropriate for its purpose.

What to consider before installing

This skill appears to implement the advertised image-generation workflow for open.skills.video and the included scripts are readable Python. Before installing: (1) Be aware you will need to provide SKILLS_VIDEO_API_KEY in your environment — the registry metadata did not declare this, so confirm you trust the author/service before exporting any API key. (2) Review any OpenAPI/docs.json files you pass to the scripts; the tool will read those files and send constructed payloads to the open.skills.video endpoints. (3) Avoid including secrets in payload fields (prompts or extra parameters) because the scripts will POST them to the remote service. (4) If you need stronger assurance, ask the publisher to update registry metadata to declare SKILLS_VIDEO_API_KEY as a required credential and to provide a provenance/homepage; absence of those increases risk. If you don't trust skills.video or the publisher, do not supply credentials.

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.

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:

• COMPLETED
• FAILED
• CANCELED

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:

• 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:

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:

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