ai-image-skills

概述

使用该技能将 OpenAPI 定义转换为适用于 skills.video 的可运行图像生成 API 调用。
优先从 openapi.json 中确定性地提取字段，而非猜测字段。

工作流

1. 首次使用时检查 API 密钥并初始化环境。
2. 识别当前生效的 OpenAPI 规范（spec）。
3. 为图像模型选择一对 SSE 端点（SSE endpoint pair）。
4. 提取请求 Schema 并生成请求载荷（payload）模板。
5. 默认执行 POST /generation/sse/... 请求，并保持流连接开启。
6. 若 SSE 流未到达终态（terminal completion），则轮询 GET /generation/{id} 直至终态。
7. 仅返回终态结果（COMPLETED/SUCCEEDED/FAILED/CANCELED），绝不返回 IN_PROGRESS。
8. 应用重试机制与失败处理逻辑。

0) 检查 API 密钥（首次运行）

在发起任何 API 调用前，必须先执行此检查。

python scripts/ensure_api_key.py

若返回结果中 ok 为 false，请提示用户执行以下操作：

• 访问 https://skills.video/dashboard/developer 并登录
• 点击 Create API Key
• 将密钥导出为环境变量 SKILLS_VIDEO_API_KEY

示例：

export SKILLS_VIDEO_API_KEY=""

1) 识别规范（spec）

优先加载最具体的 OpenAPI 规范。

• 若存在模型专属的 OpenAPI（例如位于模型命名空间下的 /v1/openapi.json），则优先选用。
• 否则回退至平台级 openapi.json。
• 基础 URL、认证方式及异步生命周期行为参考 references/open-platform-api.md。

2) 选择图像端点（image endpoint）

若存在 docs.json，则从中 Images 导航分组推导图像端点。
以脚本输出中的 default_endpoints 列表作为主候选列表（SSE 端点优先）。

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

当 docs.json 不可用时，可直接传入已知端点（例如 /generation/sse/google/nano-banana-pro）。
可参考 references/image-model-endpoints.md 获取当前快照形式的端点列表。

3) 提取 Schema 并构建请求载荷（payload）

检查端点详细信息，基于必填字段与默认值生成请求模板。

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

以返回的 request_template 为初始模板。
不得添加端点 Schema 中未定义的字段。
除非明确需要覆盖，否则应使用输出中的 default_create_endpoint。

4) 执行 SSE 请求（默认方式），并自动回退至轮询

推荐使用封装好的辅助脚本：它通过 SSE 创建任务并持续接收流；若流提前终止且未达终态，则自动切换为轮询回退模式。

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

将 SSE 视为默认的结果通道。
不得在 IN_QUEUE 或 IN_PROGRESS 状态下结束任务。
仅在获得终态结果后才返回。

5) 回退至轮询（polling）

仅在以下情形下启用轮询：SSE 连接无法建立、过早断开，或流未到达终态。
使用 GET /generation/{id}（若 OpenAPI 使用 /v1/... 路径，则采用对应模型专属路径）。

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

在以下终态时停止轮询：

• COMPLETED
• FAILED
• CANCELED

推荐使用的辅助脚本：

python scripts/wait_generation.py 
  --generation-id  
  --timeout 900 
  --interval 3

仅当该辅助脚本输出 event=terminal 后，才向用户返回结果。

6) 错误与重试处理

需对创建、SSE 及轮询回退等操作中可能出现的如下 HTTP 响应码进行处理：

• 400：请求格式错误
• 401：缺失或无效 API 密钥
• 402：运行时可能存在支付/额度问题
• 404：端点或生成 ID 不存在
• 422：Schema 校验失败

对非 2xx 的运行时错误，使用以下命令分类：

python scripts/handle_runtime_error.py 
  --status  
  --body ''

若分类结果为 insufficient_credits，请提示用户充值：

• 访问 https://skills.video/dashboard，进入 Billing/Credits 页面
• 充值或购买额外额度
• 充值完成后重试

可选：查询当前余额：

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

仅对临时性异常（如网络故障或临时性的 5xx 错误）应用重试。
采用有界指数退避策略（例如重试间隔依次为 1s、2s、4s，最大不超过 16s，之后失败退出）。
对于因 4xx 校验错误导致的失败，禁止对未修改的载荷重复重试。

速率限制与超时

除非在当前生效的 OpenAPI 或产品文档中明确定义，否则应将速率限制与服务端超时窗口视为未知。
若未知，应在输出中显式注明，并采用保守的客户端默认值。

资源

• scripts/ensure_api_key.py：校验 SKILLS_VIDEO_API_KEY 并提供首次运行设置指引
• scripts/handle_runtime_error.py：对运行时错误进行分类，并在额度不足时提供充值指引
• scripts/inspect_openapi.py：提取 SSE/轮询端点对、接口契约（contract）及请求载荷模板
• scripts/create_and_wait.py：通过 SSE 创建任务，并在流未达终态时自动回退至轮询
• scripts/wait_generation.py：轮询生成状态直至终态完成，并返回最终响应
• references/open-platform-api.md：以 SSE 为首选的生命周期设计、轮询回退机制、重试基准策略
• references/image-model-endpoints.md：基于 docs.json 的当前图像端点快照