ai-image
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.
Prerequisites
- Obtain an API key at:
https://skills.video/dashboard/developer
- Configure
SKILLS_VIDEO_API_KEY before using the skill.
Preferred OpenClaw setup:
- Open the skill settings for
ai-image
- Add an environment variable named
SKILLS_VIDEO_API_KEY
- Paste the API key as its value
Equivalent config shape:
{
"skills": {
"entries": {
"ai-image": {
"enabled": true,
"env": {
"SKILLS_VIDEO_API_KEY": "your_api_key_here"
}
}
}
}
}
Other valid ways to provide the key:
- Shell:
export SKILLS_VIDEO_API_KEY="your_api_key_here"
- Tool-specific env config: any runtime that injects
SKILLS_VIDEO_API_KEY
Workflow
- Check API key and bootstrap environment on first use.
- Identify the active spec.
- Select the SSE endpoint pair for an image model.
- Extract request schema and generate a payload template.
- Execute
POST /generation/sse/... as default and keep the stream open.
- If SSE does not reach terminal completion, poll
GET /generation/{id} to terminal status.
- Return only terminal result (
COMPLETED/SUCCEEDED/FAILED/CANCELED), never IN_PROGRESS.
- 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:
- Follow the setup in
Prerequisites
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:
COMPLETEDFAILEDCANCELED
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 issue401: missing/invalid API key402: possible payment/credits issue in runtime404: endpoint or generation id not found422: 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 guidancescripts/handle_runtime_error.py: classify runtime errors and provide recharge guidance for insufficient creditsscripts/inspect_openapi.py: extract SSE/polling endpoint pair, contract, and payload templatescripts/create_and_wait.py: create via SSE and auto-fallback to polling when stream does not reach terminal statusscripts/wait_generation.py: poll generation status until terminal completion and return final responsereferences/open-platform-api.md: SSE-first lifecycle, fallback polling, retry baselinereferences/image-model-endpoints.md: current image endpoint snapshot from docs.json
