{"id":"e2c7a777-a9e3-46fd-90e7-0e59418ad221","entityType":"agent","slug":"clawhub-youteacher-spark-media","name":"spark-media","canonicalUrl":"https://www.xpersona.co/agent/clawhub-youteacher-spark-media","canonicalPath":"/agent/clawhub-youteacher-spark-media","generatedAt":"2026-10-11T07:41:59.889Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T05:41:46.134Z","emptyReason":null},"description":"使用场景: 用户明确希望通过 AI Skills 平台 API 生成图片、编辑参考图、文生视频、图生视频、制作短视频或查询媒体任务。 Skill: spark-media Owner: youteacher Summary: 使用场景: 用户明确希望通过 AI Skills 平台 API 生成图片、编辑参考图、文生视频、图生视频、制作短视频或查询媒体任务。 Tags: latest:2.5.2 Version history: v2.5.2 | 2026-09-18T09:08:40.827Z | auto - Updated to version 2.5.2. - SKILL.md: Clarified usage scenarios, added license field, and updated packageVersion metadata. - Added completion standards on async operation handling, error retries, and multi-step/multi-file reques","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s17439knp21875y4g295ngvb3s8cwp1y:spark-media","sourceUrl":"https://clawhub.ai/youteacher/spark-media","homepage":"https://clawhub.ai/youteacher/skills/spark-media","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/youteacher/spark-media","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/youteacher/skills/spark-media","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":61,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"使用场景: 用户明确希望通过 AI Skills 平台 API 生成图片、编辑参考图、文生视频、图生视频、制作短视频或查询媒体任务。 Skill: spark-media Owner: youteacher Summary: 使用场景: 用户明确希望通过 AI Skills 平台 API 生成图片、编辑参考图、文生视频"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T05:41:46.134Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T05:41:46.134Z","emptyReason":null},"stars":null,"forks":null,"downloads":1143,"packageName":null,"latestVersion":"2.5.2","tractionLabel":"1.1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T05:41:46.121Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T05:41:46.134Z","lastCrawledAt":"2026-10-11T05:41:46.121Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T05:41:46.121Z","lastVerifiedAt":null,"highlights":[{"version":"2.5.2","createdAt":"2026-09-18T09:08:40.827Z","changelog":"- Updated to version 2.5.2. - SKILL.md: Clarified usage scenarios, added license field, and updated packageVersion metadata. - Added completion standards on async operation handling, error retries, and multi-step/multi-file request reporting. - Removed skill-card.md.","fileCount":8,"zipByteSize":7763},{"version":"2.5.0","createdAt":"2026-09-04T09:06:29.760Z","changelog":"发布 spark-media 2.5.0","fileCount":8,"zipByteSize":7525},{"version":"2.4.1","createdAt":"2026-08-28T13:28:15.364Z","changelog":"Add topics for publisher catalog grouping.","fileCount":8,"zipByteSize":7375},{"version":"2.4.0","createdAt":"2026-08-28T12:36:38.580Z","changelog":"增加 ClawHub 分类并更新 Skill 版本。","fileCount":8,"zipByteSize":7123},{"version":"2.3.0","createdAt":"2026-08-27T02:59:31.102Z","changelog":"同步本地 SKILL.md 版本与使用说明。","fileCount":8,"zipByteSize":7490},{"version":"2.2.0","createdAt":"2026-08-26T01:24:18.263Z","changelog":"Update OpenClaw configuration and skill instructions.","fileCount":8,"zipByteSize":7585},{"version":"2.1.0","createdAt":"2026-08-25T11:34:05.605Z","changelog":"Update OpenClaw configuration and skill instructions.","fileCount":8,"zipByteSize":7717},{"version":"2.0.0","createdAt":"2026-08-23T23:27:42.025Z","changelog":"Migrate Spark Media to the unified AI Skills platform API.","fileCount":8,"zipByteSize":7221}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17439knp21875y4g295ngvb3s8cwp1y:spark-media","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-youteacher-spark-media/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-youteacher-spark-media/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-youteacher-spark-media/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-youteacher-spark-media/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-youteacher-spark-media/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-youteacher-spark-media/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T07:41:59.886Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-youteacher-spark-media/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-youteacher-spark-media/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-youteacher-spark-media/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-youteacher-spark-media/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T05:41:46.134Z","emptyReason":null},"readme":"Skill: spark-media\n\nOwner: youteacher\n\nSummary: 使用场景: 用户明确希望通过 AI Skills 平台 API 生成图片、编辑参考图、文生视频、图生视频、制作短视频或查询媒体任务。\n\nTags: latest:2.5.2\n\nVersion history:\n\nv2.5.2 | 2026-09-18T09:08:40.827Z | auto\n\n- Updated to version 2.5.2.\n- SKILL.md: Clarified usage scenarios, added license field, and updated packageVersion metadata.\n- Added completion standards on async operation handling, error retries, and multi-step/multi-file request reporting.\n- Removed skill-card.md.\n\nv2.5.0 | 2026-09-04T09:06:29.760Z | user\n\n发布 spark-media 2.5.0\n\nv2.4.1 | 2026-08-28T13:28:15.364Z | user\n\nAdd topics for publisher catalog grouping.\n\nv2.4.0 | 2026-08-28T12:36:38.580Z | user\n\n增加 ClawHub 分类并更新 Skill 版本。\n\nv2.3.0 | 2026-08-27T02:59:31.102Z | user\n\n同步本地 SKILL.md 版本与使用说明。\n\nv2.2.0 | 2026-08-26T01:24:18.263Z | user\n\nUpdate OpenClaw configuration and skill instructions.\n\nv2.1.0 | 2026-08-25T11:34:05.605Z | user\n\nUpdate OpenClaw configuration and skill instructions.\n\nv2.0.0 | 2026-08-23T23:27:42.025Z | user\n\nMigrate Spark Media to the unified AI Skills platform API.\n\nv1.0.3 | 2026-07-15T11:56:31.739Z | user\n\n429 の 2 系統（日次消費上限 / レート制限）の区別と対応を明記\n\nv1.0.2 | 2026-07-15T08:54:48.691Z | user\n\nBase URL と認証ヘッダを SKILL.md に復元、Idempotency-Key の 409/422 制約を文書化\n\nv1.0.0 | 2026-07-15T02:07:02.942Z | user\n\nInitial release: text-to-image, image-to-image, text-to-video, image-to-video\n\nArchive index:\n\nArchive v2.5.2: 8 files, 7763 bytes\n\nFiles: references/API-KEY.md (606b), references/BEHAVIOR-RULES.md (1442b), references/HTTP-REQUESTS.md (1164b), references/IMAGE-GENERATION.md (1039b), references/VIDEO-GENERATION.md (1533b), skill-card.md (3112b), SKILL.md (2601b), _meta.json (130b)\n\nFile v2.5.2:SKILL.md\n\n---\nname: spark-media\ndescription: \"使用场景: 用户明确希望通过 AI Skills 平台 API 生成图片、编辑参考图、文生视频、图生视频、制作短视频或查询媒体任务。\"\nlicense: MIT-0\nmetadata:\n    {\n        \"packageVersion\": \"2.5.2\",\n        \"openclaw\":\n            {\n                \"emoji\": \"✨\",\n                \"homepage\": \"https://ai-skills.open-idea.net\",\n                \"primaryEnv\": \"SPARK_MEDIA_API_KEY\",\n                \"requires\": { \"env\": [\"SPARK_MEDIA_API_KEY\"] },\n            },\n    }\n---\n\n# Spark 媒体\n\n## Skill 简介\n\nSpark Media 用于根据文字生成图片和视频、基于参考图进行图片或视频创作，并查询媒体任务进度与结果，适合广告图、商品图、海报和短视频素材制作。\n\n## 平台入口与注册\n\n1. 打开 [AI Skills 平台](https://ai-skills.open-idea.net/)，新用户可直接进入 [注册页面](https://ai-skills.open-idea.net/register)，已有账号进入 [登录页面](https://ai-skills.open-idea.net/login)。\n2. 登录后进入 [产品管理](https://ai-skills.open-idea.net/dashboard/products) 开通本 Skill，再到 [API 密钥管理](https://ai-skills.open-idea.net/dashboard/keys) 创建密钥。\n\n## Skill 安装与配置\n\n1. 在 [API 密钥管理](https://ai-skills.open-idea.net/dashboard/keys)中选择已开通的产品，创建并复制 API 密钥。\n2. 在 OpenClaw 中安装本 Skill。\n3. 将复制的密钥配置到本 Skill 的 API 密钥环境变量，然后重启 Gateway：\n\n```sh\nopenclaw config set env.SPARK_MEDIA_API_KEY \"你的平台APIKey\"\nopenclaw gateway restart\n```\n\n## 完成标准\n\n- 异步操作提交后持续轮询任务状态，直到成功或失败的终态再汇报；不要在 pending/processing 中途停下征求许可。\n- 用户已确认的处理范围内，遇 429/503 按参考文档以原幂等键退避重试（不产生额外扣费），恢复后继续，无需再次确认。\n- 一次请求涉及多个文件或多个步骤时，全部处理完再汇报；部分失败要逐项说明哪些成功、哪些失败及原因。\n\n## 参考资料\n\n- [API 密钥配置](https://ai-skills.open-idea.net/skill-docs/spark-media/API-KEY.md)\n- [图片生成与编辑](https://ai-skills.open-idea.net/skill-docs/spark-media/IMAGE-GENERATION.md)\n- [视频生成与轮询](https://ai-skills.open-idea.net/skill-docs/spark-media/VIDEO-GENERATION.md)\n- [HTTP 请求示例](https://ai-skills.open-idea.net/skill-docs/spark-media/HTTP-REQUESTS.md)\n- [行为、错误与重试规则](https://ai-skills.open-idea.net/skill-docs/spark-media/BEHAVIOR-RULES.md)\n\nFile v2.5.2:_meta.json\n\n{\n  \"ownerId\": \"kn7114n7fws0zkhdbtpvy92sp182gqge\",\n  \"slug\": \"spark-media\",\n  \"version\": \"2.5.2\",\n  \"publishedAt\": 1789722520827\n}\n\nFile v2.5.2:references/API-KEY.md\n\n# API 密钥配置\n\n\n```bash\nexport SPARK_MEDIA_API_KEY=\"ais_...\"\nexport AI_SKILLS_API_URL=\"https://ai-skills.open-idea.net\" # 可选\n```\n\n请求根地址为 `${AI_SKILLS_API_URL:-https://ai-skills.open-idea.net}/api/v1`。\n\n```text\nAuthorization: Bearer $SPARK_MEDIA_API_KEY\n```\n\n密钥仅绑定 Spark Media，不能跨 Skill 使用。不要要求用户在聊天中粘贴完整密钥，也不要\n将密钥写入代码、提示词、日志或生成文件。常见鉴权错误包括 `invalid_api_key`、\n`key_expired`、`key_revoked`、`skill_not_active`、`user_skill_suspended` 和\n`account_suspended`。\n\nFile v2.5.2:references/BEHAVIOR-RULES.md\n\n# 行为、错误与重试规则\n\n## 安全与质量\n\n- 不生成违法、有害或侵犯隐私的内容；涉及真人敏感编辑时先核实授权。\n- 图像输入只上传完成任务所需内容，敏感图片上传前取得同意。\n- 结果字段缺失、解码失败或任务状态未知时明确报告异常，不伪造媒体。\n- 保存、移动、重命名或再次展示现有结果时禁止重新生成。\n\n## 幂等与错误\n\n- 四个创建接口都必须有 `Idempotency-Key`；同一请求重试复用原值，参数变化才换新值。\n- `validation_failed`（验证失败）：修正尺寸、格式、时长、画幅或字段。\n- `insufficient_balance`（余额不足）：提示充值，不自动创建新任务。\n- `rate_limited`（受到速率限制）：遵循 `Retry-After` 或有限指数退避。\n- `upstream_unavailable`（上游服务不可用）：短暂退避后复用原幂等键重试，限制次数。\n- `idempotency_in_progress`（幂等请求处理中）：等待原请求，不换密钥并发提交。\n- `idempotency_indeterminate`（幂等结果不确定）：停止自动重试并核对原请求、任务和账单。\n- `video_task_in_progress`（视频任务处理中）：查询现有任务，不能绕过单活跃任务限制。\n\n幂等重放返回首次响应与首次计费头。统一计费头为\n`X-AI-Skills-Billing-Currency`、`X-AI-Skills-Billing-Charged`、\n`X-AI-Skills-Billing-Balance`。\n\nFile v2.5.2:references/HTTP-REQUESTS.md\n\n# HTTP 请求示例\n\n```bash\nAPI_ROOT=\"${AI_SKILLS_API_URL:-https://ai-skills.open-idea.net}/api/v1\"\n\ncurl --fail-with-body \"$API_ROOT/spark-media/image\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: image-uuid-001\" \\\n  -d '{\"prompt\":\"雪山下的藏式村庄，电影感光线\",\"width\":1024,\"height\":1024,\"count\":1}'\n```\n\n```bash\ncurl --fail-with-body \"$API_ROOT/spark-media/video\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: video-uuid-001\" \\\n  -d '{\"prompt\":\"云层缓慢掠过雪山\",\"duration\":5,\"resolution\":\"720p\",\"ratio\":\"16:9\",\"watermark\":false}'\n```\n\n创建返回 HTTP 202 后：\n\n```bash\ncurl --fail-with-body \"$API_ROOT/spark-media/video/TASK_ID\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\"\n```\n\n图生图和图生视频将完整的 `data:image/png;base64,...` 放进 JSON 的 `image` 字段；不要\n使用 multipart。生产中使用 UUID 等真正唯一的幂等键。\n\n创建响应的计费头是 `X-AI-Skills-Billing-Currency`、\n`X-AI-Skills-Billing-Charged`、`X-AI-Skills-Billing-Balance`。\n\nFile v2.5.2:references/IMAGE-GENERATION.md\n\n# 图片生成与编辑\n\n## 文生图\n\n`POST /api/v1/spark-media/image`\n\n| 字段 | 约束 |\n|---|---|\n| `prompt` | 必填，最多 8000 字符 |\n| `width`、`height` | 可选，各 512–4096 |\n| `count` | 可选，1–4 |\n\n## 图生图\n\n`POST /api/v1/spark-media/image/edit`\n\n除 `prompt`、`width`、`height` 外，必须提供 JSON 字段 `image`。其值是完整的 PNG、\nJPEG 或 WebP `data:` URL，例如 `data:image/png;base64,...`；不是 multipart 文件。\n解码后的图片不得超过 5 MB。\n\n两个接口都要求：\n\n```text\nAuthorization: Bearer ...\nIdempotency-Key: 每个新逻辑请求的唯一值\nContent-Type: application/json\n```\n\n保持用户要求的主体、构图、文字和风格。编辑图片时以用户提供的原图为事实来源；不要为了\n下载、改名、移动或再次展示结果而重新调用生成接口。响应中的媒体字段由上游模型决定，\n应解析并持久化实际返回内容；不要假设始终是某一种 URL 结构，也不要在聊天中输出完整\nbase64。\n\nFile v2.5.2:references/VIDEO-GENERATION.md\n\n# 视频生成与轮询\n\n## 创建任务\n\n- 文生视频：`POST /api/v1/spark-media/video`\n- 图生视频：`POST /api/v1/spark-media/video/image`\n\nJSON 参数：\n\n| 字段 | 约束 |\n|---|---|\n| `prompt` | 必填，最多 8000 字符 |\n| `duration` | 可选，`5` 或 `10` 秒 |\n| `resolution` | 可选，`480p`、`720p` 或 `1080p` |\n| `ratio` | 可选，`16:9`、`9:16` 或 `1:1` |\n| `watermark` | 可选，布尔值 |\n| `image` | 仅图生视频必填；PNG/JPEG/WebP `data:` URL，解码后最大 5 MB |\n\n两个创建接口都要求 `Idempotency-Key`，成功返回 HTTP 202、`task_id` 和初始 `status`。\n平台同一用户同一时刻只允许一个活跃视频任务；HTTP 409\n`video_task_in_progress`（视频任务处理中）表示应继续查询已有任务，不要创建并行任务。\n\n## 查询任务\n\n`GET /api/v1/spark-media/video/{task_id}`\n\n每 5–10 秒轮询一次并限制总时长。`pending`（等待中）、`submitted`（已提交）、`queued`（已排队）、`running`（运行中）等状态\n视为进行中；`succeeded`（成功）为成功；`failed`（失败）、`error`、`cancelled`（已取消）、`canceled`（已取消）为终态失败。\n成功后读取响应中的 `video_url` 或 `result` 并立即保存需要的内容。\n\n`refunded: true` 表示失败任务的本次费用已退回。不要仅凭失败文本自行宣称退款；以该字段\n及账单记录为准。失败状态不能当作可无限重试的理由，新任务必须由用户意图或明确恢复策略\n驱动。\n\nFile v2.5.2:skill-card.md\n\n## Description:\n\nSpark Media helps agents generate and edit images, create text-to-video or image-to-video media, produce short video assets, and query media task status through the AI Skills platform API.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[youteacher](https://clawhub.ai/user/youteacher)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and developers use this skill to route AI image and video generation, reference-image editing, short media creation, and media task status checks through the Spark Media API.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Prompts, reference images, and generated media task data are sent to the Spark Media service.\n\nMitigation: Use the skill only for intended Spark Media workflows, avoid sensitive images or prompts without consent, and disclose external processing where appropriate.\n\nRisk: The skill requires a Spark Media API key.\n\nMitigation: Use a scoped API key and keep it out of chats, generated files, logs, and source code.\n\nRisk: Image or video generation requests may incur charges and can be affected by retries or uncertain task state.\n\nMitigation: Reuse the original idempotency key when retrying 429 or 503 responses, stop on indeterminate idempotency results, and verify task and billing status before submitting replacement jobs.\n\nRisk: Media generation or editing can produce harmful, unlawful, misleading, or privacy-invasive content.\n\nMitigation: Do not generate unlawful or harmful content, verify authorization before sensitive edits involving real people, and report missing or malformed result fields instead of fabricating media.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/youteacher/skills/spark-media)\n- [AI Skills platform](https://ai-skills.open-idea.net)\n- [API key configuration](https://ai-skills.open-idea.net/skill-docs/spark-media/API-KEY.md)\n- [Image generation and editing](https://ai-skills.open-idea.net/skill-docs/spark-media/IMAGE-GENERATION.md)\n- [Video generation and polling](https://ai-skills.open-idea.net/skill-docs/spark-media/VIDEO-GENERATION.md)\n- [HTTP request examples](https://ai-skills.open-idea.net/skill-docs/spark-media/HTTP-REQUESTS.md)\n- [Behavior, errors, and retry rules](https://ai-skills.open-idea.net/skill-docs/spark-media/BEHAVIOR-RULES.md)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Markdown, Shell commands, Configuration, API calls]\n\n**Output Format:** [Markdown with inline shell commands and JSON HTTP examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include task identifiers, status summaries, billing-header interpretation, and saved media references; requires SPARK_MEDIA_API_KEY.]\n\n## Skill Version(s):\n\n2.5.2 (source: ClawHub release metadata and skill metadata.packageVersion)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v2.5.0: 8 files, 7525 bytes\n\nFiles: references/API-KEY.md (606b), references/BEHAVIOR-RULES.md (1442b), references/HTTP-REQUESTS.md (1164b), references/IMAGE-GENERATION.md (1039b), references/VIDEO-GENERATION.md (1533b), skill-card.md (3276b), SKILL.md (2105b), _meta.json (130b)\n\nFile v2.5.0:SKILL.md\n\n---\nname: spark-media\ndescription: \"使用场景: 用户要求生成图片、编辑参考图、文生视频、图生视频、制作短视频或查询媒体任务；需要 SPARK_MEDIA_API_KEY。\"\nmetadata:\n    {\n        \"packageVersion\": \"2.5.0\",\n        \"openclaw\":\n            {\n                \"emoji\": \"✨\",\n                \"homepage\": \"https://ai-skills.open-idea.net\",\n                \"primaryEnv\": \"SPARK_MEDIA_API_KEY\",\n                \"requires\": { \"env\": [\"SPARK_MEDIA_API_KEY\"] },\n            },\n    }\n---\n\n# Spark 媒体\n\n## Skill 简介\n\nSpark Media 用于根据文字生成图片和视频、基于参考图进行图片或视频创作，并查询媒体任务进度与结果，适合广告图、商品图、海报和短视频素材制作。\n\n## 平台入口与注册\n\n1. 打开 [AI Skills 平台](https://ai-skills.open-idea.net/)，新用户可直接进入 [注册页面](https://ai-skills.open-idea.net/register)，已有账号进入 [登录页面](https://ai-skills.open-idea.net/login)。\n2. 登录后进入 [产品管理](https://ai-skills.open-idea.net/dashboard/products) 开通本 Skill，再到 [API 密钥管理](https://ai-skills.open-idea.net/dashboard/keys) 创建密钥。\n\n## Skill 安装与配置\n\n1. 在 [API 密钥管理](https://ai-skills.open-idea.net/dashboard/keys)中选择已开通的产品，创建并复制 API 密钥。\n2. 在 OpenClaw 中安装本 Skill。\n3. 将复制的密钥配置到本 Skill 的 API 密钥环境变量，然后重启 Gateway：\n\n```sh\nopenclaw config set env.SPARK_MEDIA_API_KEY \"你的平台APIKey\"\nopenclaw gateway restart\n```\n\n## 参考资料\n\n- [API 密钥配置](https://ai-skills.open-idea.net/skill-docs/spark-media/API-KEY.md)\n- [图片生成与编辑](https://ai-skills.open-idea.net/skill-docs/spark-media/IMAGE-GENERATION.md)\n- [视频生成与轮询](https://ai-skills.open-idea.net/skill-docs/spark-media/VIDEO-GENERATION.md)\n- [HTTP 请求示例](https://ai-skills.open-idea.net/skill-docs/spark-media/HTTP-REQUESTS.md)\n- [行为、错误与重试规则](https://ai-skills.open-idea.net/skill-docs/spark-media/BEHAVIOR-RULES.md)\n\nFile v2.5.0:_meta.json\n\n{\n  \"ownerId\": \"kn7114n7fws0zkhdbtpvy92sp182gqge\",\n  \"slug\": \"spark-media\",\n  \"version\": \"2.5.0\",\n  \"publishedAt\": 1788512789760\n}\n\nFile v2.5.0:references/API-KEY.md\n\n# API 密钥配置\n\n\n```bash\nexport SPARK_MEDIA_API_KEY=\"ais_...\"\nexport AI_SKILLS_API_URL=\"https://ai-skills.open-idea.net\" # 可选\n```\n\n请求根地址为 `${AI_SKILLS_API_URL:-https://ai-skills.open-idea.net}/api/v1`。\n\n```text\nAuthorization: Bearer $SPARK_MEDIA_API_KEY\n```\n\n密钥仅绑定 Spark Media，不能跨 Skill 使用。不要要求用户在聊天中粘贴完整密钥，也不要\n将密钥写入代码、提示词、日志或生成文件。常见鉴权错误包括 `invalid_api_key`、\n`key_expired`、`key_revoked`、`skill_not_active`、`user_skill_suspended` 和\n`account_suspended`。\n\nFile v2.5.0:references/BEHAVIOR-RULES.md\n\n# 行为、错误与重试规则\n\n## 安全与质量\n\n- 不生成违法、有害或侵犯隐私的内容；涉及真人敏感编辑时先核实授权。\n- 图像输入只上传完成任务所需内容，敏感图片上传前取得同意。\n- 结果字段缺失、解码失败或任务状态未知时明确报告异常，不伪造媒体。\n- 保存、移动、重命名或再次展示现有结果时禁止重新生成。\n\n## 幂等与错误\n\n- 四个创建接口都必须有 `Idempotency-Key`；同一请求重试复用原值，参数变化才换新值。\n- `validation_failed`（验证失败）：修正尺寸、格式、时长、画幅或字段。\n- `insufficient_balance`（余额不足）：提示充值，不自动创建新任务。\n- `rate_limited`（受到速率限制）：遵循 `Retry-After` 或有限指数退避。\n- `upstream_unavailable`（上游服务不可用）：短暂退避后复用原幂等键重试，限制次数。\n- `idempotency_in_progress`（幂等请求处理中）：等待原请求，不换密钥并发提交。\n- `idempotency_indeterminate`（幂等结果不确定）：停止自动重试并核对原请求、任务和账单。\n- `video_task_in_progress`（视频任务处理中）：查询现有任务，不能绕过单活跃任务限制。\n\n幂等重放返回首次响应与首次计费头。统一计费头为\n`X-AI-Skills-Billing-Currency`、`X-AI-Skills-Billing-Charged`、\n`X-AI-Skills-Billing-Balance`。\n\nFile v2.5.0:references/HTTP-REQUESTS.md\n\n# HTTP 请求示例\n\n```bash\nAPI_ROOT=\"${AI_SKILLS_API_URL:-https://ai-skills.open-idea.net}/api/v1\"\n\ncurl --fail-with-body \"$API_ROOT/spark-media/image\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: image-uuid-001\" \\\n  -d '{\"prompt\":\"雪山下的藏式村庄，电影感光线\",\"width\":1024,\"height\":1024,\"count\":1}'\n```\n\n```bash\ncurl --fail-with-body \"$API_ROOT/spark-media/video\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: video-uuid-001\" \\\n  -d '{\"prompt\":\"云层缓慢掠过雪山\",\"duration\":5,\"resolution\":\"720p\",\"ratio\":\"16:9\",\"watermark\":false}'\n```\n\n创建返回 HTTP 202 后：\n\n```bash\ncurl --fail-with-body \"$API_ROOT/spark-media/video/TASK_ID\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\"\n```\n\n图生图和图生视频将完整的 `data:image/png;base64,...` 放进 JSON 的 `image` 字段；不要\n使用 multipart。生产中使用 UUID 等真正唯一的幂等键。\n\n创建响应的计费头是 `X-AI-Skills-Billing-Currency`、\n`X-AI-Skills-Billing-Charged`、`X-AI-Skills-Billing-Balance`。\n\nFile v2.5.0:references/IMAGE-GENERATION.md\n\n# 图片生成与编辑\n\n## 文生图\n\n`POST /api/v1/spark-media/image`\n\n| 字段 | 约束 |\n|---|---|\n| `prompt` | 必填，最多 8000 字符 |\n| `width`、`height` | 可选，各 512–4096 |\n| `count` | 可选，1–4 |\n\n## 图生图\n\n`POST /api/v1/spark-media/image/edit`\n\n除 `prompt`、`width`、`height` 外，必须提供 JSON 字段 `image`。其值是完整的 PNG、\nJPEG 或 WebP `data:` URL，例如 `data:image/png;base64,...`；不是 multipart 文件。\n解码后的图片不得超过 5 MB。\n\n两个接口都要求：\n\n```text\nAuthorization: Bearer ...\nIdempotency-Key: 每个新逻辑请求的唯一值\nContent-Type: application/json\n```\n\n保持用户要求的主体、构图、文字和风格。编辑图片时以用户提供的原图为事实来源；不要为了\n下载、改名、移动或再次展示结果而重新调用生成接口。响应中的媒体字段由上游模型决定，\n应解析并持久化实际返回内容；不要假设始终是某一种 URL 结构，也不要在聊天中输出完整\nbase64。\n\nFile v2.5.0:references/VIDEO-GENERATION.md\n\n# 视频生成与轮询\n\n## 创建任务\n\n- 文生视频：`POST /api/v1/spark-media/video`\n- 图生视频：`POST /api/v1/spark-media/video/image`\n\nJSON 参数：\n\n| 字段 | 约束 |\n|---|---|\n| `prompt` | 必填，最多 8000 字符 |\n| `duration` | 可选，`5` 或 `10` 秒 |\n| `resolution` | 可选，`480p`、`720p` 或 `1080p` |\n| `ratio` | 可选，`16:9`、`9:16` 或 `1:1` |\n| `watermark` | 可选，布尔值 |\n| `image` | 仅图生视频必填；PNG/JPEG/WebP `data:` URL，解码后最大 5 MB |\n\n两个创建接口都要求 `Idempotency-Key`，成功返回 HTTP 202、`task_id` 和初始 `status`。\n平台同一用户同一时刻只允许一个活跃视频任务；HTTP 409\n`video_task_in_progress`（视频任务处理中）表示应继续查询已有任务，不要创建并行任务。\n\n## 查询任务\n\n`GET /api/v1/spark-media/video/{task_id}`\n\n每 5–10 秒轮询一次并限制总时长。`pending`（等待中）、`submitted`（已提交）、`queued`（已排队）、`running`（运行中）等状态\n视为进行中；`succeeded`（成功）为成功；`failed`（失败）、`error`、`cancelled`（已取消）、`canceled`（已取消）为终态失败。\n成功后读取响应中的 `video_url` 或 `result` 并立即保存需要的内容。\n\n`refunded: true` 表示失败任务的本次费用已退回。不要仅凭失败文本自行宣称退款；以该字段\n及账单记录为准。失败状态不能当作可无限重试的理由，新任务必须由用户意图或明确恢复策略\n驱动。\n\nFile v2.5.0:skill-card.md\n\n## Description:\n\nSpark Media helps agents generate images and videos, edit from reference images, create short media assets, and check media task status using SPARK_MEDIA_API_KEY.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[youteacher](https://clawhub.ai/user/youteacher)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and external users use this skill to route text, image-reference, and video-generation requests to the Spark Media service, including polling video jobs and preserving returned media results. It is suited for advertising images, product images, posters, and short video material when the user has configured the required API key.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Prompts and selected images are sent to the Spark Media API.\n\nMitigation: Use the skill only when the user intends to use Spark Media, upload only task-required images, and obtain consent before using sensitive images.\n\nRisk: API keys or alternate API endpoints could expose credentials or send data to an untrusted service.\n\nMitigation: Keep SPARK_MEDIA_API_KEY out of chat, code, prompts, logs, and generated files; leave AI_SKILLS_API_URL unset unless the endpoint is controlled and trusted.\n\nRisk: Retries can duplicate paid media-generation tasks or conflict with an active video job.\n\nMitigation: Use a unique Idempotency-Key per logical create request, reuse it for retries, honor Retry-After, and query existing video tasks instead of creating parallel jobs.\n\nRisk: Missing or ambiguous task results could lead to fabricated media outputs or refund claims.\n\nMitigation: Report missing fields, decoding failures, and unknown task states explicitly; rely on returned media fields, refunded flags, and billing records.\n\n## Reference(s):\n\n- [Spark Media Skill Page](https://clawhub.ai/youteacher/skills/spark-media)\n- [AI Skills Platform](https://ai-skills.open-idea.net)\n- [API Key Configuration](https://ai-skills.open-idea.net/skill-docs/spark-media/API-KEY.md)\n- [Image Generation and Editing](https://ai-skills.open-idea.net/skill-docs/spark-media/IMAGE-GENERATION.md)\n- [Video Generation and Polling](https://ai-skills.open-idea.net/skill-docs/spark-media/VIDEO-GENERATION.md)\n- [HTTP Request Examples](https://ai-skills.open-idea.net/skill-docs/spark-media/HTTP-REQUESTS.md)\n- [Behavior, Errors, and Retry Rules](https://ai-skills.open-idea.net/skill-docs/spark-media/BEHAVIOR-RULES.md)\n\n## Skill Output:\n\n**Output Type(s):** [API Calls, Files, Markdown, Shell commands, Configuration instructions, Guidance]\n\n**Output Format:** [Markdown with JSON HTTP requests, shell commands, generated media URLs or saved media files, and task-status summaries]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Uses idempotency keys for create requests, polls video tasks with bounded retries, and requires SPARK_MEDIA_API_KEY.]\n\n## Skill Version(s):\n\n2.5.0 (source: server release evidence and artifact metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v2.4.1: 8 files, 7375 bytes\n\nFiles: references/API-KEY.md (599b), references/BEHAVIOR-RULES.md (1273b), references/HTTP-REQUESTS.md (1164b), references/IMAGE-GENERATION.md (1039b), references/VIDEO-GENERATION.md (1396b), skill-card.md (3418b), SKILL.md (2094b), _meta.json (130b)\n\nFile v2.4.1:SKILL.md\n\n---\nname: spark-media\ndescription: \"使用场景: 用户要求生成图片、编辑参考图、文生视频、图生视频、制作短视频或查询媒体任务；需要 SPARK_MEDIA_API_KEY。\"\nmetadata:\n    {\n        \"packageVersion\": \"2.4.1\",\n        \"openclaw\":\n            {\n                \"emoji\": \"✨\",\n                \"homepage\": \"https://ai-skills.open-idea.net\",\n                \"primaryEnv\": \"SPARK_MEDIA_API_KEY\",\n                \"requires\": { \"env\": [\"SPARK_MEDIA_API_KEY\"] },\n            },\n    }\n---\n\n# Spark Media\n\n## Skill 简介\n\nSpark Media 用于根据文字生成图片和视频、基于参考图进行图片或视频创作，并查询媒体任务进度与结果，适合广告图、商品图、海报和短视频素材制作。\n\n## 平台入口与注册\n\n1. 打开 [AI Skills 平台](https://ai-skills.open-idea.net/)，新用户可直接进入 [注册页面](https://ai-skills.open-idea.net/register)，已有账号进入 [登录页面](https://ai-skills.open-idea.net/login)。\n2. 登录后进入 [产品管理](https://ai-skills.open-idea.net/dashboard/products) 开通本 Skill，再到 [API Key 管理](https://ai-skills.open-idea.net/dashboard/keys) 创建密钥。\n\n## API Key 获取与配置\n\n1. 在 [API Key 管理](https://ai-skills.open-idea.net/dashboard/keys)中选择已开通的产品，创建并复制 API Key。\n2. 在 OpenClaw 中安装本 Skill。\n3. 将复制的 Key 配置到本 Skill 的 API Key 环境变量，然后重启 Gateway：\n\n```sh\nopenclaw config set env.SPARK_MEDIA_API_KEY \"你的平台APIKey\"\nopenclaw gateway restart\n```\n\n## 参考资料\n\n- [API Key 配置](https://ai-skills.open-idea.net/skill-docs/spark-media/API-KEY.md)\n- [图片生成与编辑](https://ai-skills.open-idea.net/skill-docs/spark-media/IMAGE-GENERATION.md)\n- [视频生成与轮询](https://ai-skills.open-idea.net/skill-docs/spark-media/VIDEO-GENERATION.md)\n- [HTTP 请求示例](https://ai-skills.open-idea.net/skill-docs/spark-media/HTTP-REQUESTS.md)\n- [行为、错误与重试规则](https://ai-skills.open-idea.net/skill-docs/spark-media/BEHAVIOR-RULES.md)\n\nFile v2.4.1:_meta.json\n\n{\n  \"ownerId\": \"kn7114n7fws0zkhdbtpvy92sp182gqge\",\n  \"slug\": \"spark-media\",\n  \"version\": \"2.4.1\",\n  \"publishedAt\": 1787923695364\n}\n\nFile v2.4.1:references/API-KEY.md\n\n# API Key 配置\n\n\n```bash\nexport SPARK_MEDIA_API_KEY=\"ais_...\"\nexport AI_SKILLS_API_URL=\"https://ai-skills.open-idea.net\" # 可选\n```\n\n请求根地址为 `${AI_SKILLS_API_URL:-https://ai-skills.open-idea.net}/api/v1`。\n\n```text\nAuthorization: Bearer $SPARK_MEDIA_API_KEY\n```\n\nKey 仅绑定 Spark Media，不能跨 Skill 使用。不要要求用户在聊天中粘贴完整 Key，也不要\n将 Key 写入代码、提示词、日志或生成文件。常见鉴权错误包括 `invalid_api_key`、\n`key_expired`、`key_revoked`、`skill_not_active`、`user_skill_suspended` 和\n`account_suspended`。\n\nFile v2.4.1:references/BEHAVIOR-RULES.md\n\n# 行为、错误与重试规则\n\n## 安全与质量\n\n- 不生成违法、有害或侵犯隐私的内容；涉及真人敏感编辑时先核实授权。\n- 图像输入只上传完成任务所需内容，敏感图片上传前取得同意。\n- 结果字段缺失、解码失败或任务状态未知时明确报告异常，不伪造媒体。\n- 保存、移动、重命名或再次展示现有结果时禁止重新生成。\n\n## 幂等与错误\n\n- 四个创建接口都必须有 `Idempotency-Key`；同一请求重试复用原值，参数变化才换新值。\n- `validation_failed`：修正尺寸、格式、时长、画幅或字段。\n- `insufficient_balance`：提示充值，不自动创建新任务。\n- `rate_limited`：遵循 `Retry-After` 或有限指数退避。\n- `upstream_unavailable`：短暂退避后复用原幂等键重试，限制次数。\n- `idempotency_in_progress`：等待原请求，不换 Key 并发提交。\n- `idempotency_indeterminate`：停止自动重试并核对原请求、任务和账单。\n- `video_task_in_progress`：查询现有任务，不能绕过单活跃任务限制。\n\n幂等重放返回首次响应与首次计费头。统一计费头为\n`X-AI-Skills-Billing-Currency`、`X-AI-Skills-Billing-Charged`、\n`X-AI-Skills-Billing-Balance`。\n\nFile v2.4.1:references/HTTP-REQUESTS.md\n\n# HTTP 请求示例\n\n```bash\nAPI_ROOT=\"${AI_SKILLS_API_URL:-https://ai-skills.open-idea.net}/api/v1\"\n\ncurl --fail-with-body \"$API_ROOT/spark-media/image\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: image-uuid-001\" \\\n  -d '{\"prompt\":\"雪山下的藏式村庄，电影感光线\",\"width\":1024,\"height\":1024,\"count\":1}'\n```\n\n```bash\ncurl --fail-with-body \"$API_ROOT/spark-media/video\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: video-uuid-001\" \\\n  -d '{\"prompt\":\"云层缓慢掠过雪山\",\"duration\":5,\"resolution\":\"720p\",\"ratio\":\"16:9\",\"watermark\":false}'\n```\n\n创建返回 HTTP 202 后：\n\n```bash\ncurl --fail-with-body \"$API_ROOT/spark-media/video/TASK_ID\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\"\n```\n\n图生图和图生视频将完整的 `data:image/png;base64,...` 放进 JSON 的 `image` 字段；不要\n使用 multipart。生产中使用 UUID 等真正唯一的幂等键。\n\n创建响应的计费头是 `X-AI-Skills-Billing-Currency`、\n`X-AI-Skills-Billing-Charged`、`X-AI-Skills-Billing-Balance`。\n\nFile v2.4.1:references/IMAGE-GENERATION.md\n\n# 图片生成与编辑\n\n## 文生图\n\n`POST /api/v1/spark-media/image`\n\n| 字段 | 约束 |\n|---|---|\n| `prompt` | 必填，最多 8000 字符 |\n| `width`、`height` | 可选，各 512–4096 |\n| `count` | 可选，1–4 |\n\n## 图生图\n\n`POST /api/v1/spark-media/image/edit`\n\n除 `prompt`、`width`、`height` 外，必须提供 JSON 字段 `image`。其值是完整的 PNG、\nJPEG 或 WebP `data:` URL，例如 `data:image/png;base64,...`；不是 multipart 文件。\n解码后的图片不得超过 5 MB。\n\n两个接口都要求：\n\n```text\nAuthorization: Bearer ...\nIdempotency-Key: 每个新逻辑请求的唯一值\nContent-Type: application/json\n```\n\n保持用户要求的主体、构图、文字和风格。编辑图片时以用户提供的原图为事实来源；不要为了\n下载、改名、移动或再次展示结果而重新调用生成接口。响应中的媒体字段由上游模型决定，\n应解析并持久化实际返回内容；不要假设始终是某一种 URL 结构，也不要在聊天中输出完整\nbase64。\n\nFile v2.4.1:references/VIDEO-GENERATION.md\n\n# 视频生成与轮询\n\n## 创建任务\n\n- 文生视频：`POST /api/v1/spark-media/video`\n- 图生视频：`POST /api/v1/spark-media/video/image`\n\nJSON 参数：\n\n| 字段 | 约束 |\n|---|---|\n| `prompt` | 必填，最多 8000 字符 |\n| `duration` | 可选，`5` 或 `10` 秒 |\n| `resolution` | 可选，`480p`、`720p` 或 `1080p` |\n| `ratio` | 可选，`16:9`、`9:16` 或 `1:1` |\n| `watermark` | 可选，布尔值 |\n| `image` | 仅图生视频必填；PNG/JPEG/WebP `data:` URL，解码后最大 5 MB |\n\n两个创建接口都要求 `Idempotency-Key`，成功返回 HTTP 202、`task_id` 和初始 `status`。\n平台同一用户同一时刻只允许一个活跃视频任务；HTTP 409\n`video_task_in_progress` 表示应继续查询已有任务，不要创建并行任务。\n\n## 查询任务\n\n`GET /api/v1/spark-media/video/{task_id}`\n\n每 5–10 秒轮询一次并限制总时长。`pending`、`submitted`、`queued`、`running` 等状态\n视为进行中；`succeeded` 为成功；`failed`、`error`、`cancelled`、`canceled` 为终态失败。\n成功后读取响应中的 `video_url` 或 `result` 并立即保存需要的内容。\n\n`refunded: true` 表示失败任务的本次费用已退回。不要仅凭失败文本自行宣称退款；以该字段\n及账单记录为准。失败状态不能当作可无限重试的理由，新任务必须由用户意图或明确恢复策略\n驱动。\n\nFile v2.4.1:skill-card.md\n\n## Description:\n\nSpark Media helps agents generate and edit images, create text-to-video or image-to-video media, and query media task status using a configured SPARK_MEDIA_API_KEY.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[youteacher](https://clawhub.ai/user/youteacher)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and external users use this skill to guide agents through AI media generation workflows for advertising images, product images, posters, and short video assets. The skill covers API key setup, HTTP request construction, idempotent retries, task polling, and safe handling of prompts, images, media results, and billing signals.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Prompts and optional images are sent to the ai-skills.open-idea.net external service.\n\nMitigation: Confirm the service is trusted for the intended content, avoid sensitive images unless necessary and authorized, and disclose this external processing path to users where appropriate.\n\nRisk: API keys could be exposed if copied into chat, logs, generated files, or code examples.\n\nMitigation: Configure SPARK_MEDIA_API_KEY only as an environment variable and do not ask users to paste full keys into conversation.\n\nRisk: Retries or parallel video creation can duplicate work, create billing ambiguity, or conflict with the one-active-video-task limit.\n\nMitigation: Use unique Idempotency-Key values per logical request, reuse the same key for retries, follow Retry-After or bounded backoff, and poll existing video tasks instead of submitting parallel replacements.\n\n## Reference(s):\n\n- [Spark Media ClawHub listing](https://clawhub.ai/youteacher/skills/spark-media)\n- [AI Skills platform homepage](https://ai-skills.open-idea.net)\n- [API Key configuration](https://ai-skills.open-idea.net/skill-docs/spark-media/API-KEY.md)\n- [Image generation and editing](https://ai-skills.open-idea.net/skill-docs/spark-media/IMAGE-GENERATION.md)\n- [Video generation and polling](https://ai-skills.open-idea.net/skill-docs/spark-media/VIDEO-GENERATION.md)\n- [HTTP request examples](https://ai-skills.open-idea.net/skill-docs/spark-media/HTTP-REQUESTS.md)\n- [Behavior, errors, and retry rules](https://ai-skills.open-idea.net/skill-docs/spark-media/BEHAVIOR-RULES.md)\n- [Local API key reference](references/API-KEY.md)\n- [Local image generation reference](references/IMAGE-GENERATION.md)\n- [Local video generation reference](references/VIDEO-GENERATION.md)\n- [Local HTTP requests reference](references/HTTP-REQUESTS.md)\n- [Local behavior and retry reference](references/BEHAVIOR-RULES.md)\n\n## Skill Output:\n\n**Output Type(s):** [guidance, shell commands, configuration, API calls]\n\n**Output Format:** [Markdown with inline shell, HTTP, JSON, and task-status guidance]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Uses SPARK_MEDIA_API_KEY and optional AI_SKILLS_API_URL; image and video creation requests require Idempotency-Key values; video tasks are polled until terminal status.]\n\n## Skill Version(s):\n\n2.4.1 (source: server release evidence and package metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v2.4.0: 8 files, 7123 bytes\n\nFiles: references/API-KEY.md (599b), references/BEHAVIOR-RULES.md (1273b), references/HTTP-REQUESTS.md (1164b), references/IMAGE-GENERATION.md (1039b), references/VIDEO-GENERATION.md (1396b), skill-card.md (2756b), SKILL.md (2094b), _meta.json (130b)\n\nFile v2.4.0:SKILL.md\n\n---\nname: spark-media\ndescription: \"使用场景: 用户要求生成图片、编辑参考图、文生视频、图生视频、制作短视频或查询媒体任务；需要 SPARK_MEDIA_API_KEY。\"\nmetadata:\n    {\n        \"packageVersion\": \"2.4.0\",\n        \"openclaw\":\n            {\n                \"emoji\": \"✨\",\n                \"homepage\": \"https://ai-skills.open-idea.net\",\n                \"primaryEnv\": \"SPARK_MEDIA_API_KEY\",\n                \"requires\": { \"env\": [\"SPARK_MEDIA_API_KEY\"] },\n            },\n    }\n---\n\n# Spark Media\n\n## Skill 简介\n\nSpark Media 用于根据文字生成图片和视频、基于参考图进行图片或视频创作，并查询媒体任务进度与结果，适合广告图、商品图、海报和短视频素材制作。\n\n## 平台入口与注册\n\n1. 打开 [AI Skills 平台](https://ai-skills.open-idea.net/)，新用户可直接进入 [注册页面](https://ai-skills.open-idea.net/register)，已有账号进入 [登录页面](https://ai-skills.open-idea.net/login)。\n2. 登录后进入 [产品管理](https://ai-skills.open-idea.net/dashboard/products) 开通本 Skill，再到 [API Key 管理](https://ai-skills.open-idea.net/dashboard/keys) 创建密钥。\n\n## API Key 获取与配置\n\n1. 在 [API Key 管理](https://ai-skills.open-idea.net/dashboard/keys)中选择已开通的产品，创建并复制 API Key。\n2. 在 OpenClaw 中安装本 Skill。\n3. 将复制的 Key 配置到本 Skill 的 API Key 环境变量，然后重启 Gateway：\n\n```sh\nopenclaw config set env.SPARK_MEDIA_API_KEY \"你的平台APIKey\"\nopenclaw gateway restart\n```\n\n## 参考资料\n\n- [API Key 配置](https://ai-skills.open-idea.net/skill-docs/spark-media/API-KEY.md)\n- [图片生成与编辑](https://ai-skills.open-idea.net/skill-docs/spark-media/IMAGE-GENERATION.md)\n- [视频生成与轮询](https://ai-skills.open-idea.net/skill-docs/spark-media/VIDEO-GENERATION.md)\n- [HTTP 请求示例](https://ai-skills.open-idea.net/skill-docs/spark-media/HTTP-REQUESTS.md)\n- [行为、错误与重试规则](https://ai-skills.open-idea.net/skill-docs/spark-media/BEHAVIOR-RULES.md)\n\nFile v2.4.0:_meta.json\n\n{\n  \"ownerId\": \"kn7114n7fws0zkhdbtpvy92sp182gqge\",\n  \"slug\": \"spark-media\",\n  \"version\": \"2.4.0\",\n  \"publishedAt\": 1787920598580\n}\n\nFile v2.4.0:references/API-KEY.md\n\n# API Key 配置\n\n\n```bash\nexport SPARK_MEDIA_API_KEY=\"ais_...\"\nexport AI_SKILLS_API_URL=\"https://ai-skills.open-idea.net\" # 可选\n```\n\n请求根地址为 `${AI_SKILLS_API_URL:-https://ai-skills.open-idea.net}/api/v1`。\n\n```text\nAuthorization: Bearer $SPARK_MEDIA_API_KEY\n```\n\nKey 仅绑定 Spark Media，不能跨 Skill 使用。不要要求用户在聊天中粘贴完整 Key，也不要\n将 Key 写入代码、提示词、日志或生成文件。常见鉴权错误包括 `invalid_api_key`、\n`key_expired`、`key_revoked`、`skill_not_active`、`user_skill_suspended` 和\n`account_suspended`。\n\nFile v2.4.0:references/BEHAVIOR-RULES.md\n\n# 行为、错误与重试规则\n\n## 安全与质量\n\n- 不生成违法、有害或侵犯隐私的内容；涉及真人敏感编辑时先核实授权。\n- 图像输入只上传完成任务所需内容，敏感图片上传前取得同意。\n- 结果字段缺失、解码失败或任务状态未知时明确报告异常，不伪造媒体。\n- 保存、移动、重命名或再次展示现有结果时禁止重新生成。\n\n## 幂等与错误\n\n- 四个创建接口都必须有 `Idempotency-Key`；同一请求重试复用原值，参数变化才换新值。\n- `validation_failed`：修正尺寸、格式、时长、画幅或字段。\n- `insufficient_balance`：提示充值，不自动创建新任务。\n- `rate_limited`：遵循 `Retry-After` 或有限指数退避。\n- `upstream_unavailable`：短暂退避后复用原幂等键重试，限制次数。\n- `idempotency_in_progress`：等待原请求，不换 Key 并发提交。\n- `idempotency_indeterminate`：停止自动重试并核对原请求、任务和账单。\n- `video_task_in_progress`：查询现有任务，不能绕过单活跃任务限制。\n\n幂等重放返回首次响应与首次计费头。统一计费头为\n`X-AI-Skills-Billing-Currency`、`X-AI-Skills-Billing-Charged`、\n`X-AI-Skills-Billing-Balance`。\n\nFile v2.4.0:references/HTTP-REQUESTS.md\n\n# HTTP 请求示例\n\n```bash\nAPI_ROOT=\"${AI_SKILLS_API_URL:-https://ai-skills.open-idea.net}/api/v1\"\n\ncurl --fail-with-body \"$API_ROOT/spark-media/image\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: image-uuid-001\" \\\n  -d '{\"prompt\":\"雪山下的藏式村庄，电影感光线\",\"width\":1024,\"height\":1024,\"count\":1}'\n```\n\n```bash\ncurl --fail-with-body \"$API_ROOT/spark-media/video\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: video-uuid-001\" \\\n  -d '{\"prompt\":\"云层缓慢掠过雪山\",\"duration\":5,\"resolution\":\"720p\",\"ratio\":\"16:9\",\"watermark\":false}'\n```\n\n创建返回 HTTP 202 后：\n\n```bash\ncurl --fail-with-body \"$API_ROOT/spark-media/video/TASK_ID\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\"\n```\n\n图生图和图生视频将完整的 `data:image/png;base64,...` 放进 JSON 的 `image` 字段；不要\n使用 multipart。生产中使用 UUID 等真正唯一的幂等键。\n\n创建响应的计费头是 `X-AI-Skills-Billing-Currency`、\n`X-AI-Skills-Billing-Charged`、`X-AI-Skills-Billing-Balance`。\n\nFile v2.4.0:references/IMAGE-GENERATION.md\n\n# 图片生成与编辑\n\n## 文生图\n\n`POST /api/v1/spark-media/image`\n\n| 字段 | 约束 |\n|---|---|\n| `prompt` | 必填，最多 8000 字符 |\n| `width`、`height` | 可选，各 512–4096 |\n| `count` | 可选，1–4 |\n\n## 图生图\n\n`POST /api/v1/spark-media/image/edit`\n\n除 `prompt`、`width`、`height` 外，必须提供 JSON 字段 `image`。其值是完整的 PNG、\nJPEG 或 WebP `data:` URL，例如 `data:image/png;base64,...`；不是 multipart 文件。\n解码后的图片不得超过 5 MB。\n\n两个接口都要求：\n\n```text\nAuthorization: Bearer ...\nIdempotency-Key: 每个新逻辑请求的唯一值\nContent-Type: application/json\n```\n\n保持用户要求的主体、构图、文字和风格。编辑图片时以用户提供的原图为事实来源；不要为了\n下载、改名、移动或再次展示结果而重新调用生成接口。响应中的媒体字段由上游模型决定，\n应解析并持久化实际返回内容；不要假设始终是某一种 URL 结构，也不要在聊天中输出完整\nbase64。\n\nFile v2.4.0:references/VIDEO-GENERATION.md\n\n# 视频生成与轮询\n\n## 创建任务\n\n- 文生视频：`POST /api/v1/spark-media/video`\n- 图生视频：`POST /api/v1/spark-media/video/image`\n\nJSON 参数：\n\n| 字段 | 约束 |\n|---|---|\n| `prompt` | 必填，最多 8000 字符 |\n| `duration` | 可选，`5` 或 `10` 秒 |\n| `resolution` | 可选，`480p`、`720p` 或 `1080p` |\n| `ratio` | 可选，`16:9`、`9:16` 或 `1:1` |\n| `watermark` | 可选，布尔值 |\n| `image` | 仅图生视频必填；PNG/JPEG/WebP `data:` URL，解码后最大 5 MB |\n\n两个创建接口都要求 `Idempotency-Key`，成功返回 HTTP 202、`task_id` 和初始 `status`。\n平台同一用户同一时刻只允许一个活跃视频任务；HTTP 409\n`video_task_in_progress` 表示应继续查询已有任务，不要创建并行任务。\n\n## 查询任务\n\n`GET /api/v1/spark-media/video/{task_id}`\n\n每 5–10 秒轮询一次并限制总时长。`pending`、`submitted`、`queued`、`running` 等状态\n视为进行中；`succeeded` 为成功；`failed`、`error`、`cancelled`、`canceled` 为终态失败。\n成功后读取响应中的 `video_url` 或 `result` 并立即保存需要的内容。\n\n`refunded: true` 表示失败任务的本次费用已退回。不要仅凭失败文本自行宣称退款；以该字段\n及账单记录为准。失败状态不能当作可无限重试的理由，新任务必须由用户意图或明确恢复策略\n驱动。\n\nFile v2.4.0:skill-card.md\n\n## Description:\n\nGenerates images, edits reference images, creates text-to-video and image-to-video tasks, and checks media task progress using the Spark Media API and SPARK_MEDIA_API_KEY.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[youteacher](https://clawhub.ai/user/youteacher)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal creators, marketers, and developers use Spark Media to generate or edit image assets, create short video clips, and poll task results through a configured API key.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Prompts and reference images are transmitted to the Spark Media service.\n\nMitigation: Avoid sending sensitive images or personal data unless consent is established, and upload only what is required for the task.\n\nRisk: The API key can expose account access and billing if pasted into chat, code, logs, or generated files.\n\nMitigation: Keep SPARK_MEDIA_API_KEY in environment configuration and do not reproduce full keys in prompts or outputs.\n\nRisk: Media generation and retries can incur account charges.\n\nMitigation: Use Idempotency-Key for creation requests, respect rate limits and Retry-After, and stop when task state or billing is indeterminate.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/youteacher/skills/spark-media)\n- [AI Skills Platform](https://ai-skills.open-idea.net)\n- [API Key Configuration](https://ai-skills.open-idea.net/skill-docs/spark-media/API-KEY.md)\n- [Image Generation and Editing](https://ai-skills.open-idea.net/skill-docs/spark-media/IMAGE-GENERATION.md)\n- [Video Generation and Polling](https://ai-skills.open-idea.net/skill-docs/spark-media/VIDEO-GENERATION.md)\n- [HTTP Request Examples](https://ai-skills.open-idea.net/skill-docs/spark-media/HTTP-REQUESTS.md)\n- [Behavior, Errors, and Retry Rules](https://ai-skills.open-idea.net/skill-docs/spark-media/BEHAVIOR-RULES.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance, files]\n\n**Output Format:** [Markdown guidance with shell commands, API request examples, task status summaries, and saved image or video result references.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Requires SPARK_MEDIA_API_KEY; prompts and reference images are sent to the Spark Media service and may incur account charges.]\n\n## Skill Version(s):\n\n2.4.0 (source: server evidence release.version and packageVersion metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v2.3.0: 8 files, 7490 bytes\n\nFiles: references/API-KEY.md (599b), references/BEHAVIOR-RULES.md (1273b), references/HTTP-REQUESTS.md (1164b), references/IMAGE-GENERATION.md (1039b), references/VIDEO-GENERATION.md (1396b), skill-card.md (3256b), SKILL.md (2274b), _meta.json (130b)\n\nFile v2.3.0:SKILL.md\n\n---\nname: spark-media\ndescription: \"使用场景: 用户要求生成图片、编辑参考图、文生视频、图生视频、制作短视频或查询媒体任务；需要 SPARK_MEDIA_API_KEY。\"\nmetadata:\n    {\n        \"packageVersion\": \"2.3.0\",\n        \"openclaw\":\n            {\n                \"emoji\": \"✨\",\n                \"homepage\": \"https://ai-skills.open-idea.net\",\n                \"primaryEnv\": \"SPARK_MEDIA_API_KEY\",\n                \"requires\": { \"env\": [\"SPARK_MEDIA_API_KEY\"] },\n            },\n    }\n---\n\n# Spark Media\n\n## Skill 简介\n\nSpark Media 用于根据文字生成图片和视频、基于参考图进行图片或视频创作，并查询媒体任务进度与结果，适合广告图、商品图、海报和短视频素材制作。\n\n## 平台入口与注册\n\n1. 打开 [AI Skills 平台](https://ai-skills.open-idea.net/)，新用户可直接进入 [注册页面](https://ai-skills.open-idea.net/register)，已有账号进入 [登录页面](https://ai-skills.open-idea.net/login)。\n2. 登录后进入 [产品管理](https://ai-skills.open-idea.net/dashboard/products) 开通本 Skill，再到 [API Key 管理](https://ai-skills.open-idea.net/dashboard/keys) 创建密钥。\n\n## API Key 获取与配置\n\n1. 在 [API Key 管理](https://ai-skills.open-idea.net/dashboard/keys)中选择已开通的产品，创建并复制 API Key。\n2. 在 OpenClaw 中安装本 Skill。\n3. 将复制的 Key 配置到本 Skill 的 API Key 环境变量，然后重启 Gateway：\n\n```sh\nopenclaw config set env.SPARK_MEDIA_API_KEY \"你的平台APIKey\"\nopenclaw gateway restart\n```\n\n## 参考资料\n\n- [API Key 配置](https://github.com/YouTeacher/ai-skills-platform/blob/main/openclaw/spark-media/references/API-KEY.md)\n- [图片生成与编辑](https://github.com/YouTeacher/ai-skills-platform/blob/main/openclaw/spark-media/references/IMAGE-GENERATION.md)\n- [视频生成与轮询](https://github.com/YouTeacher/ai-skills-platform/blob/main/openclaw/spark-media/references/VIDEO-GENERATION.md)\n- [HTTP 请求示例](https://github.com/YouTeacher/ai-skills-platform/blob/main/openclaw/spark-media/references/HTTP-REQUESTS.md)\n- [行为、错误与重试规则](https://github.com/YouTeacher/ai-skills-platform/blob/main/openclaw/spark-media/references/BEHAVIOR-RULES.md)\n\nFile v2.3.0:_meta.json\n\n{\n  \"ownerId\": \"kn7114n7fws0zkhdbtpvy92sp182gqge\",\n  \"slug\": \"spark-media\",\n  \"version\": \"2.3.0\",\n  \"publishedAt\": 1787799571102\n}\n\nFile v2.3.0:references/API-KEY.md\n\n# API Key 配置\n\n\n```bash\nexport SPARK_MEDIA_API_KEY=\"ais_...\"\nexport AI_SKILLS_API_URL=\"https://ai-skills.open-idea.net\" # 可选\n```\n\n请求根地址为 `${AI_SKILLS_API_URL:-https://ai-skills.open-idea.net}/api/v1`。\n\n```text\nAuthorization: Bearer $SPARK_MEDIA_API_KEY\n```\n\nKey 仅绑定 Spark Media，不能跨 Skill 使用。不要要求用户在聊天中粘贴完整 Key，也不要\n将 Key 写入代码、提示词、日志或生成文件。常见鉴权错误包括 `invalid_api_key`、\n`key_expired`、`key_revoked`、`skill_not_active`、`user_skill_suspended` 和\n`account_suspended`。\n\nFile v2.3.0:references/BEHAVIOR-RULES.md\n\n# 行为、错误与重试规则\n\n## 安全与质量\n\n- 不生成违法、有害或侵犯隐私的内容；涉及真人敏感编辑时先核实授权。\n- 图像输入只上传完成任务所需内容，敏感图片上传前取得同意。\n- 结果字段缺失、解码失败或任务状态未知时明确报告异常，不伪造媒体。\n- 保存、移动、重命名或再次展示现有结果时禁止重新生成。\n\n## 幂等与错误\n\n- 四个创建接口都必须有 `Idempotency-Key`；同一请求重试复用原值，参数变化才换新值。\n- `validation_failed`：修正尺寸、格式、时长、画幅或字段。\n- `insufficient_balance`：提示充值，不自动创建新任务。\n- `rate_limited`：遵循 `Retry-After` 或有限指数退避。\n- `upstream_unavailable`：短暂退避后复用原幂等键重试，限制次数。\n- `idempotency_in_progress`：等待原请求，不换 Key 并发提交。\n- `idempotency_indeterminate`：停止自动重试并核对原请求、任务和账单。\n- `video_task_in_progress`：查询现有任务，不能绕过单活跃任务限制。\n\n幂等重放返回首次响应与首次计费头。统一计费头为\n`X-AI-Skills-Billing-Currency`、`X-AI-Skills-Billing-Charged`、\n`X-AI-Skills-Billing-Balance`。\n\nFile v2.3.0:references/HTTP-REQUESTS.md\n\n# HTTP 请求示例\n\n```bash\nAPI_ROOT=\"${AI_SKILLS_API_URL:-https://ai-skills.open-idea.net}/api/v1\"\n\ncurl --fail-with-body \"$API_ROOT/spark-media/image\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: image-uuid-001\" \\\n  -d '{\"prompt\":\"雪山下的藏式村庄，电影感光线\",\"width\":1024,\"height\":1024,\"count\":1}'\n```\n\n```bash\ncurl --fail-with-body \"$API_ROOT/spark-media/video\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: video-uuid-001\" \\\n  -d '{\"prompt\":\"云层缓慢掠过雪山\",\"duration\":5,\"resolution\":\"720p\",\"ratio\":\"16:9\",\"watermark\":false}'\n```\n\n创建返回 HTTP 202 后：\n\n```bash\ncurl --fail-with-body \"$API_ROOT/spark-media/video/TASK_ID\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\"\n```\n\n图生图和图生视频将完整的 `data:image/png;base64,...` 放进 JSON 的 `image` 字段；不要\n使用 multipart。生产中使用 UUID 等真正唯一的幂等键。\n\n创建响应的计费头是 `X-AI-Skills-Billing-Currency`、\n`X-AI-Skills-Billing-Charged`、`X-AI-Skills-Billing-Balance`。\n\nFile v2.3.0:references/IMAGE-GENERATION.md\n\n# 图片生成与编辑\n\n## 文生图\n\n`POST /api/v1/spark-media/image`\n\n| 字段 | 约束 |\n|---|---|\n| `prompt` | 必填，最多 8000 字符 |\n| `width`、`height` | 可选，各 512–4096 |\n| `count` | 可选，1–4 |\n\n## 图生图\n\n`POST /api/v1/spark-media/image/edit`\n\n除 `prompt`、`width`、`height` 外，必须提供 JSON 字段 `image`。其值是完整的 PNG、\nJPEG 或 WebP `data:` URL，例如 `data:image/png;base64,...`；不是 multipart 文件。\n解码后的图片不得超过 5 MB。\n\n两个接口都要求：\n\n```text\nAuthorization: Bearer ...\nIdempotency-Key: 每个新逻辑请求的唯一值\nContent-Type: application/json\n```\n\n保持用户要求的主体、构图、文字和风格。编辑图片时以用户提供的原图为事实来源；不要为了\n下载、改名、移动或再次展示结果而重新调用生成接口。响应中的媒体字段由上游模型决定，\n应解析并持久化实际返回内容；不要假设始终是某一种 URL 结构，也不要在聊天中输出完整\nbase64。\n\nFile v2.3.0:references/VIDEO-GENERATION.md\n\n# 视频生成与轮询\n\n## 创建任务\n\n- 文生视频：`POST /api/v1/spark-media/video`\n- 图生视频：`POST /api/v1/spark-media/video/image`\n\nJSON 参数：\n\n| 字段 | 约束 |\n|---|---|\n| `prompt` | 必填，最多 8000 字符 |\n| `duration` | 可选，`5` 或 `10` 秒 |\n| `resolution` | 可选，`480p`、`720p` 或 `1080p` |\n| `ratio` | 可选，`16:9`、`9:16` 或 `1:1` |\n| `watermark` | 可选，布尔值 |\n| `image` | 仅图生视频必填；PNG/JPEG/WebP `data:` URL，解码后最大 5 MB |\n\n两个创建接口都要求 `Idempotency-Key`，成功返回 HTTP 202、`task_id` 和初始 `status`。\n平台同一用户同一时刻只允许一个活跃视频任务；HTTP 409\n`video_task_in_progress` 表示应继续查询已有任务，不要创建并行任务。\n\n## 查询任务\n\n`GET /api/v1/spark-media/video/{task_id}`\n\n每 5–10 秒轮询一次并限制总时长。`pending`、`submitted`、`queued`、`running` 等状态\n视为进行中；`succeeded` 为成功；`failed`、`error`、`cancelled`、`canceled` 为终态失败。\n成功后读取响应中的 `video_url` 或 `result` 并立即保存需要的内容。\n\n`refunded: true` 表示失败任务的本次费用已退回。不要仅凭失败文本自行宣称退款；以该字段\n及账单记录为准。失败状态不能当作可无限重试的理由，新任务必须由用户意图或明确恢复策略\n驱动。\n\nFile v2.3.0:skill-card.md\n\n## Description:\n\nSpark Media helps agents generate images and videos from prompts, edit or animate reference images, create short media assets, and query media task status using SPARK_MEDIA_API_KEY.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[youteacher](https://clawhub.ai/user/youteacher)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and developers use this skill to create advertising images, product images, posters, short videos, and other media assets through the Spark Media service. It is also used to poll media generation tasks and retrieve completed results.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill uses SPARK_MEDIA_API_KEY to call an external Spark Media API, so leaked credentials could allow unauthorized generation requests or account charges.\n\nMitigation: Store SPARK_MEDIA_API_KEY only as a secret environment variable, do not paste full keys into chat, code, logs, prompts, or generated files, and verify AI_SKILLS_API_URL points to the intended endpoint.\n\nRisk: Prompts and reference images may be uploaded to the Spark Media service, including sensitive or user-provided image content.\n\nMitigation: Upload only content needed for the task, obtain consent before sensitive image uploads or edits involving real people, and avoid unlawful, harmful, or privacy-invasive media generation.\n\nRisk: Generation calls may consume account balance, and retries or duplicate submissions can create unintended costs.\n\nMitigation: Use a unique Idempotency-Key for each new logical request, reuse the same key for retries, follow Retry-After or bounded backoff, and stop automatic retries when idempotency or billing state is indeterminate.\n\nRisk: Media task responses may be missing fields, fail decoding, or have unknown status.\n\nMitigation: Report abnormal responses clearly, do not fabricate media outputs, and rely on returned result fields and billing records instead of assumptions.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/youteacher/skills/spark-media)\n- [AI Skills Platform](https://ai-skills.open-idea.net)\n- [API Key Configuration](artifact/references/API-KEY.md)\n- [Image Generation and Editing](artifact/references/IMAGE-GENERATION.md)\n- [Video Generation and Polling](artifact/references/VIDEO-GENERATION.md)\n- [HTTP Request Examples](artifact/references/HTTP-REQUESTS.md)\n- [Behavior, Errors, and Retry Rules](artifact/references/BEHAVIOR-RULES.md)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Shell commands, API Calls, Configuration]\n\n**Output Format:** [Markdown with inline shell commands, HTTP request examples, and media task guidance]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May direct agents to submit prompts or reference images to an external media generation service and poll asynchronous video tasks.]\n\n## Skill Version(s):\n\n2.3.0 (source: server release evidence and skill metadata packageVersion)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v2.2.0: 8 files, 7585 bytes\n\nFiles: references/API-KEY.md (599b), references/BEHAVIOR-RULES.md (1273b), references/HTTP-REQUESTS.md (1164b), references/IMAGE-GENERATION.md (1039b), references/VIDEO-GENERATION.md (1396b), skill-card.md (2555b), SKILL.md (3167b), _meta.json (130b)\n\nFile v2.2.0:SKILL.md\n\n---\nname: spark-media\ndescription: \"使用场景: 用户要求生成图片、编辑参考图、文生视频、图生视频、制作短视频或查询媒体任务；需要 SPARK_MEDIA_API_KEY。\"\nmetadata:\n    {\n        \"packageVersion\": \"2.2.0\",\n        \"openclaw\":\n            {\n                \"emoji\": \"✨\",\n                \"homepage\": \"https://ai-skills.open-idea.net\",\n                \"primaryEnv\": \"SPARK_MEDIA_API_KEY\",\n                \"requires\": { \"env\": [\"SPARK_MEDIA_API_KEY\"] },\n            },\n    }\n---\n\n# Spark Media\n\n## Skill 简介\n\nSpark Media 用于根据文字生成图片和视频、基于参考图进行图片或视频创作，并查询媒体任务进度与结果，适合广告图、商品图、海报和短视频素材制作。\n\n## API Key 获取与配置\n\n1. 注册并登录 AI Skills 平台，在「产品管理」中开通 Spark Media。\n2. 进入「API Key」，选择该产品，创建并复制 API Key。\n3. 在 OpenClaw 中安装本 Skill。\n4. 将复制的 Key 配置到本 Skill 的 API Key 环境变量，然后重启 Gateway：\n\n```sh\nopenclaw config set env.SPARK_MEDIA_API_KEY \"你的平台APIKey\"\nopenclaw gateway restart\n```\n\n不要把完整 Key 发到对话中或写入代码、日志和生成文件。\n\n统一处理文生图、图生图、文生视频和图生视频。默认 API 根地址为\n`https://ai-skills.open-idea.net/api/v1`。\n\n## 工作流程\n\n1. 检查 [API Key 配置](https://github.com/YouTeacher/ai-skills-platform/blob/main/openclaw/spark-media/references/API-KEY.md)，不要输出完整 Key。\n2. 图片任务读取 [图片生成与编辑](https://github.com/YouTeacher/ai-skills-platform/blob/main/openclaw/spark-media/references/IMAGE-GENERATION.md)。\n3. 视频任务读取 [视频生成与轮询](https://github.com/YouTeacher/ai-skills-platform/blob/main/openclaw/spark-media/references/VIDEO-GENERATION.md)。\n4. 四个创建接口均必须携带唯一 `Idempotency-Key`。\n5. 用户未指定但会显著影响结果的尺寸、画幅或时长应先确认；其余参数可采用安全默认值。\n\n## 交付规则\n\n- 保存并返回本次响应已有的媒体结果，不为“保存”“移动”“下载”再次生成。\n- 不在对话中展开完整 base64 data URL。\n- 视频创建返回 HTTP 202 和 `task_id` 后持续轮询，直到成功、失败或明确超时。\n- 需要展示计费时读取 `X-AI-Skills-Billing-Currency`、\n  `X-AI-Skills-Billing-Charged`、`X-AI-Skills-Billing-Balance`。\n\n## 参考资料\n\n- [API Key 配置](https://github.com/YouTeacher/ai-skills-platform/blob/main/openclaw/spark-media/references/API-KEY.md)\n- [图片生成与编辑](https://github.com/YouTeacher/ai-skills-platform/blob/main/openclaw/spark-media/references/IMAGE-GENERATION.md)\n- [视频生成与轮询](https://github.com/YouTeacher/ai-skills-platform/blob/main/openclaw/spark-media/references/VIDEO-GENERATION.md)\n- [HTTP 请求示例](https://github.com/YouTeacher/ai-skills-platform/blob/main/openclaw/spark-media/references/HTTP-REQUESTS.md)\n- [行为、错误与重试规则](https://github.com/YouTeacher/ai-skills-platform/blob/main/openclaw/spark-media/references/BEHAVIOR-RULES.md)\n\nFile v2.2.0:_meta.json\n\n{\n  \"ownerId\": \"kn7114n7fws0zkhdbtpvy92sp182gqge\",\n  \"slug\": \"spark-media\",\n  \"version\": \"2.2.0\",\n  \"publishedAt\": 1787707458263\n}\n\nFile v2.2.0:references/API-KEY.md\n\n# API Key 配置\n\n\n```bash\nexport SPARK_MEDIA_API_KEY=\"ais_...\"\nexport AI_SKILLS_API_URL=\"https://ai-skills.open-idea.net\" # 可选\n```\n\n请求根地址为 `${AI_SKILLS_API_URL:-https://ai-skills.open-idea.net}/api/v1`。\n\n```text\nAuthorization: Bearer $SPARK_MEDIA_API_KEY\n```\n\nKey 仅绑定 Spark Media，不能跨 Skill 使用。不要要求用户在聊天中粘贴完整 Key，也不要\n将 Key 写入代码、提示词、日志或生成文件。常见鉴权错误包括 `invalid_api_key`、\n`key_expired`、`key_revoked`、`skill_not_active`、`user_skill_suspended` 和\n`account_suspended`。\n\nFile v2.2.0:references/BEHAVIOR-RULES.md\n\n# 行为、错误与重试规则\n\n## 安全与质量\n\n- 不生成违法、有害或侵犯隐私的内容；涉及真人敏感编辑时先核实授权。\n- 图像输入只上传完成任务所需内容，敏感图片上传前取得同意。\n- 结果字段缺失、解码失败或任务状态未知时明确报告异常，不伪造媒体。\n- 保存、移动、重命名或再次展示现有结果时禁止重新生成。\n\n## 幂等与错误\n\n- 四个创建接口都必须有 `Idempotency-Key`；同一请求重试复用原值，参数变化才换新值。\n- `validation_failed`：修正尺寸、格式、时长、画幅或字段。\n- `insufficient_balance`：提示充值，不自动创建新任务。\n- `rate_limited`：遵循 `Retry-After` 或有限指数退避。\n- `upstream_unavailable`：短暂退避后复用原幂等键重试，限制次数。\n- `idempotency_in_progress`：等待原请求，不换 Key 并发提交。\n- `idempotency_indeterminate`：停止自动重试并核对原请求、任务和账单。\n- `video_task_in_progress`：查询现有任务，不能绕过单活跃任务限制。\n\n幂等重放返回首次响应与首次计费头。统一计费头为\n`X-AI-Skills-Billing-Currency`、`X-AI-Skills-Billing-Charged`、\n`X-AI-Skills-Billing-Balance`。\n\nFile v2.2.0:references/HTTP-REQUESTS.md\n\n# HTTP 请求示例\n\n```bash\nAPI_ROOT=\"${AI_SKILLS_API_URL:-https://ai-skills.open-idea.net}/api/v1\"\n\ncurl --fail-with-body \"$API_ROOT/spark-media/image\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: image-uuid-001\" \\\n  -d '{\"prompt\":\"雪山下的藏式村庄，电影感光线\",\"width\":1024,\"height\":1024,\"count\":1}'\n```\n\n```bash\ncurl --fail-with-body \"$API_ROOT/spark-media/video\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: video-uuid-001\" \\\n  -d '{\"prompt\":\"云层缓慢掠过雪山\",\"duration\":5,\"resolution\":\"720p\",\"ratio\":\"16:9\",\"watermark\":false}'\n```\n\n创建返回 HTTP 202 后：\n\n```bash\ncurl --fail-with-body \"$API_ROOT/spark-media/video/TASK_ID\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\"\n```\n\n图生图和图生视频将完整的 `data:image/png;base64,...` 放进 JSON 的 `image` 字段；不要\n使用 multipart。生产中使用 UUID 等真正唯一的幂等键。\n\n创建响应的计费头是 `X-AI-Skills-Billing-Currency`、\n`X-AI-Skills-Billing-Charged`、`X-AI-Skills-Billing-Balance`。\n\nFile v2.2.0:references/IMAGE-GENERATION.md\n\n# 图片生成与编辑\n\n## 文生图\n\n`POST /api/v1/spark-media/image`\n\n| 字段 | 约束 |\n|---|---|\n| `prompt` | 必填，最多 8000 字符 |\n| `width`、`height` | 可选，各 512–4096 |\n| `count` | 可选，1–4 |\n\n## 图生图\n\n`POST /api/v1/spark-media/image/edit`\n\n除 `prompt`、`width`、`height` 外，必须提供 JSON 字段 `image`。其值是完整的 PNG、\nJPEG 或 WebP `data:` URL，例如 `data:image/png;base64,...`；不是 multipart 文件。\n解码后的图片不得超过 5 MB。\n\n两个接口都要求：\n\n```text\nAuthorization: Bearer ...\nIdempotency-Key: 每个新逻辑请求的唯一值\nContent-Type: application/json\n```\n\n保持用户要求的主体、构图、文字和风格。编辑图片时以用户提供的原图为事实来源；不要为了\n下载、改名、移动或再次展示结果而重新调用生成接口。响应中的媒体字段由上游模型决定，\n应解析并持久化实际返回内容；不要假设始终是某一种 URL 结构，也不要在聊天中输出完整\nbase64。\n\nFile v2.2.0:references/VIDEO-GENERATION.md\n\n# 视频生成与轮询\n\n## 创建任务\n\n- 文生视频：`POST /api/v1/spark-media/video`\n- 图生视频：`POST /api/v1/spark-media/video/image`\n\nJSON 参数：\n\n| 字段 | 约束 |\n|---|---|\n| `prompt` | 必填，最多 8000 字符 |\n| `duration` | 可选，`5` 或 `10` 秒 |\n| `resolution` | 可选，`480p`、`720p` 或 `1080p` |\n| `ratio` | 可选，`16:9`、`9:16` 或 `1:1` |\n| `watermark` | 可选，布尔值 |\n| `image` | 仅图生视频必填；PNG/JPEG/WebP `data:` URL，解码后最大 5 MB |\n\n两个创建接口都要求 `Idempotency-Key`，成功返回 HTTP 202、`task_id` 和初始 `status`。\n平台同一用户同一时刻只允许一个活跃视频任务；HTTP 409\n`video_task_in_progress` 表示应继续查询已有任务，不要创建并行任务。\n\n## 查询任务\n\n`GET /api/v1/spark-media/video/{task_id}`\n\n每 5–10 秒轮询一次并限制总时长。`pending`、`submitted`、`queued`、`running` 等状态\n视为进行中；`succeeded` 为成功；`failed`、`error`、`cancelled`、`canceled` 为终态失败。\n成功后读取响应中的 `video_url` 或 `result` 并立即保存需要的内容。\n\n`refunded: true` 表示失败任务的本次费用已退回。不要仅凭失败文本自行宣称退款；以该字段\n及账单记录为准。失败状态不能当作可无限重试的理由，新任务必须由用户意图或明确恢复策略\n驱动。\n\nFile v2.2.0:skill-card.md\n\n## Description:\n\nSpark Media helps agents generate and edit images, create text-to-video or image-to-video media, and query media task status using a Spark Media API key.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[youteacher](https://clawhub.ai/user/youteacher)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and developers use this skill to request generated or edited images, create short video assets, and check asynchronous media generation results. It is suited for advertising images, product visuals, posters, and short-form media materials.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Prompts and reference images are sent to the Spark Media API.\n\nMitigation: Avoid uploading sensitive or private images unless consent is confirmed and the endpoint is trusted.\n\nRisk: The skill requires SPARK_MEDIA_API_KEY for authenticated API calls.\n\nMitigation: Keep the API key out of chats, code, logs, prompts, and generated files.\n\nRisk: Media generation may incur usage charges.\n\nMitigation: Confirm cost-sensitive requests and review billing headers or account balance when charges are relevant.\n\nRisk: Retries or duplicate create requests can create unintended media tasks.\n\nMitigation: Use a unique Idempotency-Key for each logical creation request and reuse it for retries of the same request.\n\n## Reference(s):\n\n- [Spark Media Skill Page](https://clawhub.ai/youteacher/skills/spark-media)\n- [AI Skills Platform](https://ai-skills.open-idea.net)\n- [API Key Configuration](artifact/references/API-KEY.md)\n- [Image Generation and Editing](artifact/references/IMAGE-GENERATION.md)\n- [Video Generation and Polling](artifact/references/VIDEO-GENERATION.md)\n- [Behavior, Errors, and Retry Rules](artifact/references/BEHAVIOR-RULES.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands, API request examples, task status summaries, and media result references.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May return or save generated media results; avoids printing full base64 data URLs.]\n\n## Skill Version(s):\n\n2.2.0 (source: release evidence and skill metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v2.1.0: 8 files, 7717 bytes\n\nFiles: references/API-KEY.md (599b), references/BEHAVIOR-RULES.md (1273b), references/HTTP-REQUESTS.md (1164b), references/IMAGE-GENERATION.md (1039b), references/VIDEO-GENERATION.md (1396b), skill-card.md (3091b), SKILL.md (2947b), _meta.json (130b)\n\nFile v2.1.0:SKILL.md\n\n---\nname: spark-media\ndescription: \"使用场景: 用户要求生成图片、编辑参考图、文生视频、图生视频、制作短视频或查询媒体任务；需要 SPARK_MEDIA_API_KEY。\"\nmetadata:\n    {\n        \"packageVersion\": \"2.1.0\",\n        \"openclaw\":\n            {\n                \"emoji\": \"✨\",\n                \"homepage\": \"https://ai-skills.open-idea.net\",\n                \"primaryEnv\": \"SPARK_MEDIA_API_KEY\",\n                \"requires\": { \"env\": [\"SPARK_MEDIA_API_KEY\"] },\n            },\n    }\n---\n\n# Spark Media\n\n## API Key 获取与配置\n\n1. 注册并登录 AI Skills 平台，在「产品管理」中开通 Spark Media。\n2. 进入「API Key」，选择该产品，创建并复制 API Key。\n3. 在 OpenClaw 中安装本 Skill。\n4. 将复制的 Key 配置到本 Skill 的 API Key 环境变量，然后重启 Gateway：\n\n```sh\nopenclaw config set env.SPARK_MEDIA_API_KEY \"你的平台APIKey\"\nopenclaw gateway restart\n```\n\n不要把完整 Key 发到对话中或写入代码、日志和生成文件。\n\n统一处理文生图、图生图、文生视频和图生视频。默认 API 根地址为\n`https://ai-skills.open-idea.net/api/v1`。\n\n## 工作流程\n\n1. 检查 [API Key 配置](https://github.com/YouTeacher/ai-skills-platform/blob/main/openclaw/spark-media/references/API-KEY.md)，不要输出完整 Key。\n2. 图片任务读取 [图片生成与编辑](https://github.com/YouTeacher/ai-skills-platform/blob/main/openclaw/spark-media/references/IMAGE-GENERATION.md)。\n3. 视频任务读取 [视频生成与轮询](https://github.com/YouTeacher/ai-skills-platform/blob/main/openclaw/spark-media/references/VIDEO-GENERATION.md)。\n4. 四个创建接口均必须携带唯一 `Idempotency-Key`。\n5. 用户未指定但会显著影响结果的尺寸、画幅或时长应先确认；其余参数可采用安全默认值。\n\n## 交付规则\n\n- 保存并返回本次响应已有的媒体结果，不为“保存”“移动”“下载”再次生成。\n- 不在对话中展开完整 base64 data URL。\n- 视频创建返回 HTTP 202 和 `task_id` 后持续轮询，直到成功、失败或明确超时。\n- 需要展示计费时读取 `X-AI-Skills-Billing-Currency`、\n  `X-AI-Skills-Billing-Charged`、`X-AI-Skills-Billing-Balance`。\n\n## 参考资料\n\n- [API Key 配置](https://github.com/YouTeacher/ai-skills-platform/blob/main/openclaw/spark-media/references/API-KEY.md)\n- [图片生成与编辑](https://github.com/YouTeacher/ai-skills-platform/blob/main/openclaw/spark-media/references/IMAGE-GENERATION.md)\n- [视频生成与轮询](https://github.com/YouTeacher/ai-skills-platform/blob/main/openclaw/spark-media/references/VIDEO-GENERATION.md)\n- [HTTP 请求示例](https://github.com/YouTeacher/ai-skills-platform/blob/main/openclaw/spark-media/references/HTTP-REQUESTS.md)\n- [行为、错误与重试规则](https://github.com/YouTeacher/ai-skills-platform/blob/main/openclaw/spark-media/references/BEHAVIOR-RULES.md)\n\nFile v2.1.0:_meta.json\n\n{\n  \"ownerId\": \"kn7114n7fws0zkhdbtpvy92sp182gqge\",\n  \"slug\": \"spark-media\",\n  \"version\": \"2.1.0\",\n  \"publishedAt\": 1787657645605\n}\n\nFile v2.1.0:references/API-KEY.md\n\n# API Key 配置\n\n\n```bash\nexport SPARK_MEDIA_API_KEY=\"ais_...\"\nexport AI_SKILLS_API_URL=\"https://ai-skills.open-idea.net\" # 可选\n```\n\n请求根地址为 `${AI_SKILLS_API_URL:-https://ai-skills.open-idea.net}/api/v1`。\n\n```text\nAuthorization: Bearer $SPARK_MEDIA_API_KEY\n```\n\nKey 仅绑定 Spark Media，不能跨 Skill 使用。不要要求用户在聊天中粘贴完整 Key，也不要\n将 Key 写入代码、提示词、日志或生成文件。常见鉴权错误包括 `invalid_api_key`、\n`key_expired`、`key_revoked`、`skill_not_active`、`user_skill_suspended` 和\n`account_suspended`。\n\nFile v2.1.0:references/BEHAVIOR-RULES.md\n\n# 行为、错误与重试规则\n\n## 安全与质量\n\n- 不生成违法、有害或侵犯隐私的内容；涉及真人敏感编辑时先核实授权。\n- 图像输入只上传完成任务所需内容，敏感图片上传前取得同意。\n- 结果字段缺失、解码失败或任务状态未知时明确报告异常，不伪造媒体。\n- 保存、移动、重命名或再次展示现有结果时禁止重新生成。\n\n## 幂等与错误\n\n- 四个创建接口都必须有 `Idempotency-Key`；同一请求重试复用原值，参数变化才换新值。\n- `validation_failed`：修正尺寸、格式、时长、画幅或字段。\n- `insufficient_balance`：提示充值，不自动创建新任务。\n- `rate_limited`：遵循 `Retry-After` 或有限指数退避。\n- `upstream_unavailable`：短暂退避后复用原幂等键重试，限制次数。\n- `idempotency_in_progress`：等待原请求，不换 Key 并发提交。\n- `idempotency_indeterminate`：停止自动重试并核对原请求、任务和账单。\n- `video_task_in_progress`：查询现有任务，不能绕过单活跃任务限制。\n\n幂等重放返回首次响应与首次计费头。统一计费头为\n`X-AI-Skills-Billing-Currency`、`X-AI-Skills-Billing-Charged`、\n`X-AI-Skills-Billing-Balance`。\n\nFile v2.1.0:references/HTTP-REQUESTS.md\n\n# HTTP 请求示例\n\n```bash\nAPI_ROOT=\"${AI_SKILLS_API_URL:-https://ai-skills.open-idea.net}/api/v1\"\n\ncurl --fail-with-body \"$API_ROOT/spark-media/image\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: image-uuid-001\" \\\n  -d '{\"prompt\":\"雪山下的藏式村庄，电影感光线\",\"width\":1024,\"height\":1024,\"count\":1}'\n```\n\n```bash\ncurl --fail-with-body \"$API_ROOT/spark-media/video\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: video-uuid-001\" \\\n  -d '{\"prompt\":\"云层缓慢掠过雪山\",\"duration\":5,\"resolution\":\"720p\",\"ratio\":\"16:9\",\"watermark\":false}'\n```\n\n创建返回 HTTP 202 后：\n\n```bash\ncurl --fail-with-body \"$API_ROOT/spark-media/video/TASK_ID\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\"\n```\n\n图生图和图生视频将完整的 `data:image/png;base64,...` 放进 JSON 的 `image` 字段；不要\n使用 multipart。生产中使用 UUID 等真正唯一的幂等键。\n\n创建响应的计费头是 `X-AI-Skills-Billing-Currency`、\n`X-AI-Skills-Billing-Charged`、`X-AI-Skills-Billing-Balance`。\n\nFile v2.1.0:references/IMAGE-GENERATION.md\n\n# 图片生成与编辑\n\n## 文生图\n\n`POST /api/v1/spark-media/image`\n\n| 字段 | 约束 |\n|---|---|\n| `prompt` | 必填，最多 8000 字符 |\n| `width`、`height` | 可选，各 512–4096 |\n| `count` | 可选，1–4 |\n\n## 图生图\n\n`POST /api/v1/spark-media/image/edit`\n\n除 `prompt`、`width`、`height` 外，必须提供 JSON 字段 `image`。其值是完整的 PNG、\nJPEG 或 WebP `data:` URL，例如 `data:image/png;base64,...`；不是 multipart 文件。\n解码后的图片不得超过 5 MB。\n\n两个接口都要求：\n\n```text\nAuthorization: Bearer ...\nIdempotency-Key: 每个新逻辑请求的唯一值\nContent-Type: application/json\n```\n\n保持用户要求的主体、构图、文字和风格。编辑图片时以用户提供的原图为事实来源；不要为了\n下载、改名、移动或再次展示结果而重新调用生成接口。响应中的媒体字段由上游模型决定，\n应解析并持久化实际返回内容；不要假设始终是某一种 URL 结构，也不要在聊天中输出完整\nbase64。\n\nFile v2.1.0:references/VIDEO-GENERATION.md\n\n# 视频生成与轮询\n\n## 创建任务\n\n- 文生视频：`POST /api/v1/spark-media/video`\n- 图生视频：`POST /api/v1/spark-media/video/image`\n\nJSON 参数：\n\n| 字段 | 约束 |\n|---|---|\n| `prompt` | 必填，最多 8000 字符 |\n| `duration` | 可选，`5` 或 `10` 秒 |\n| `resolution` | 可选，`480p`、`720p` 或 `1080p` |\n| `ratio` | 可选，`16:9`、`9:16` 或 `1:1` |\n| `watermark` | 可选，布尔值 |\n| `image` | 仅图生视频必填；PNG/JPEG/WebP `data:` URL，解码后最大 5 MB |\n\n两个创建接口都要求 `Idempotency-Key`，成功返回 HTTP 202、`task_id` 和初始 `status`。\n平台同一用户同一时刻只允许一个活跃视频任务；HTTP 409\n`video_task_in_progress` 表示应继续查询已有任务，不要创建并行任务。\n\n## 查询任务\n\n`GET /api/v1/spark-media/video/{task_id}`\n\n每 5–10 秒轮询一次并限制总时长。`pending`、`submitted`、`queued`、`running` 等状态\n视为进行中；`succeeded` 为成功；`failed`、`error`、`cancelled`、`canceled` 为终态失败。\n成功后读取响应中的 `video_url` 或 `result` 并立即保存需要的内容。\n\n`refunded: true` 表示失败任务的本次费用已退回。不要仅凭失败文本自行宣称退款；以该字段\n及账单记录为准。失败状态不能当作可无限重试的理由，新任务必须由用户意图或明确恢复策略\n驱动。\n\nFile v2.1.0:skill-card.md\n\n## Description:\n\nSpark Media helps agents create and edit images, create videos from text or images, and check media task status using a configured Spark Media API key.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[youteacher](https://clawhub.ai/user/youteacher)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and external users use this skill to route image generation, image editing, text-to-video, image-to-video, and media task lookup requests through the Spark Media service. It is intended for workflows where an agent must configure the API key, call the correct media endpoint, poll video tasks, and return saved media results without exposing secrets.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Prompts and uploaded reference images are sent to the Spark Media service and may contain sensitive content.\n\nMitigation: Tell users before uploading sensitive images, upload only content needed for the requested task, and avoid sensitive images unless the user consents.\n\nRisk: The configured API key can be exposed through chat, logs, code, prompts, or generated files.\n\nMitigation: Keep SPARK_MEDIA_API_KEY out of chat and generated artifacts, and use environment configuration instead of embedding the key in requests shown to users.\n\nRisk: Media generation requests may incur charges or fail because of balance, rate limit, or upstream availability conditions.\n\nMitigation: Surface billing information when relevant, respect Retry-After and bounded retry behavior, and do not automatically create new billable tasks after insufficient-balance or ambiguous idempotency responses.\n\nRisk: Retrying create requests without idempotency controls can duplicate billable media generation work.\n\nMitigation: Use a unique Idempotency-Key for each new logical create request and reuse the original value when retrying the same request.\n\n## Reference(s):\n\n- [Spark Media Homepage](https://ai-skills.open-idea.net)\n- [API Key Configuration](references/API-KEY.md)\n- [Image Generation and Editing](references/IMAGE-GENERATION.md)\n- [Video Generation and Polling](references/VIDEO-GENERATION.md)\n- [HTTP Request Examples](references/HTTP-REQUESTS.md)\n- [Behavior, Error, and Retry Rules](references/BEHAVIOR-RULES.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance, files]\n\n**Output Format:** [Markdown guidance with shell commands, API request examples, task status summaries, and saved media result references]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include billing-header summaries and media URLs or saved file references; avoids emitting full API keys or full base64 data URLs.]\n\n## Skill Version(s):\n\n2.1.0 (source: server release evidence and skill metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v2.0.0: 8 files, 7221 bytes\n\nFiles: references/API-KEY.md (598b), references/BEHAVIOR-RULES.md (1273b), references/HTTP-REQUESTS.md (1164b), references/IMAGE-GENERATION.md (1039b), references/VIDEO-GENERATION.md (1396b), skill-card.md (2711b), SKILL.md (1729b), _meta.json (130b)\n\nFile v2.0.0:SKILL.md\n\n---\nname: spark-media\ndescription: Use when 用户要求生成图片、编辑参考图、文生视频、图生视频、制作短视频或查询媒体任务；需要 SPARK_MEDIA_API_KEY。\nmetadata: {\"packageVersion\":\"2.0.0\",\"openclaw\":{\"emoji\":\"✨\",\"homepage\":\"https://ai-skills.open-idea.net\",\"primaryEnv\":\"SPARK_MEDIA_API_KEY\",\"requires\":{\"env\":[\"SPARK_MEDIA_API_KEY\"]}}}\n---\n\n# Spark Media\n\n统一处理文生图、图生图、文生视频和图生视频。默认 API 根地址为\n`https://ai-skills.open-idea.net/api/v1`，可用 `AI_SKILLS_API_URL` 覆盖站点根地址。\n\n## 工作流程\n\n1. 检查 [API Key 配置](references/API-KEY.md)，不要输出完整 Key。\n2. 图片任务读取 [图片生成与编辑](references/IMAGE-GENERATION.md)。\n3. 视频任务读取 [视频生成与轮询](references/VIDEO-GENERATION.md)。\n4. 四个创建接口均必须携带唯一 `Idempotency-Key`。\n5. 用户未指定但会显著影响结果的尺寸、画幅或时长应先确认；其余参数可采用安全默认值。\n\n## 交付规则\n\n- 保存并返回本次响应已有的媒体结果，不为“保存”“移动”“下载”再次生成。\n- 不在对话中展开完整 base64 data URL。\n- 视频创建返回 HTTP 202 和 `task_id` 后持续轮询，直到成功、失败或明确超时。\n- 需要展示计费时读取 `X-AI-Skills-Billing-Currency`、\n  `X-AI-Skills-Billing-Charged`、`X-AI-Skills-Billing-Balance`。\n\n## 参考资料\n\n- [API Key 配置](references/API-KEY.md)\n- [图片生成与编辑](references/IMAGE-GENERATION.md)\n- [视频生成与轮询](references/VIDEO-GENERATION.md)\n- [HTTP 请求示例](references/HTTP-REQUESTS.md)\n- [行为、错误与重试规则](references/BEHAVIOR-RULES.md)\n\nFile v2.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn7114n7fws0zkhdbtpvy92sp182gqge\",\n  \"slug\": \"spark-media\",\n  \"version\": \"2.0.0\",\n  \"publishedAt\": 1787527662025\n}\n\nFile v2.0.0:references/API-KEY.md\n\n# API Key 配置\n\n```bash\nexport SPARK_MEDIA_API_KEY=\"ais_...\"\nexport AI_SKILLS_API_URL=\"https://ai-skills.open-idea.net\" # 可选\n```\n\n请求根地址为 `${AI_SKILLS_API_URL:-https://ai-skills.open-idea.net}/api/v1`。\n\n```text\nAuthorization: Bearer $SPARK_MEDIA_API_KEY\n```\n\nKey 仅绑定 Spark Media，不能跨 Skill 使用。不要要求用户在聊天中粘贴完整 Key，也不要\n将 Key 写入代码、提示词、日志或生成文件。常见鉴权错误包括 `invalid_api_key`、\n`key_expired`、`key_revoked`、`skill_not_active`、`user_skill_suspended` 和\n`account_suspended`。\n\nFile v2.0.0:references/BEHAVIOR-RULES.md\n\n# 行为、错误与重试规则\n\n## 安全与质量\n\n- 不生成违法、有害或侵犯隐私的内容；涉及真人敏感编辑时先核实授权。\n- 图像输入只上传完成任务所需内容，敏感图片上传前取得同意。\n- 结果字段缺失、解码失败或任务状态未知时明确报告异常，不伪造媒体。\n- 保存、移动、重命名或再次展示现有结果时禁止重新生成。\n\n## 幂等与错误\n\n- 四个创建接口都必须有 `Idempotency-Key`；同一请求重试复用原值，参数变化才换新值。\n- `validation_failed`：修正尺寸、格式、时长、画幅或字段。\n- `insufficient_balance`：提示充值，不自动创建新任务。\n- `rate_limited`：遵循 `Retry-After` 或有限指数退避。\n- `upstream_unavailable`：短暂退避后复用原幂等键重试，限制次数。\n- `idempotency_in_progress`：等待原请求，不换 Key 并发提交。\n- `idempotency_indeterminate`：停止自动重试并核对原请求、任务和账单。\n- `video_task_in_progress`：查询现有任务，不能绕过单活跃任务限制。\n\n幂等重放返回首次响应与首次计费头。统一计费头为\n`X-AI-Skills-Billing-Currency`、`X-AI-Skills-Billing-Charged`、\n`X-AI-Skills-Billing-Balance`。\n\nFile v2.0.0:references/HTTP-REQUESTS.md\n\n# HTTP 请求示例\n\n```bash\nAPI_ROOT=\"${AI_SKILLS_API_URL:-https://ai-skills.open-idea.net}/api/v1\"\n\ncurl --fail-with-body \"$API_ROOT/spark-media/image\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: image-uuid-001\" \\\n  -d '{\"prompt\":\"雪山下的藏式村庄，电影感光线\",\"width\":1024,\"height\":1024,\"count\":1}'\n```\n\n```bash\ncurl --fail-with-body \"$API_ROOT/spark-media/video\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: video-uuid-001\" \\\n  -d '{\"prompt\":\"云层缓慢掠过雪山\",\"duration\":5,\"resolution\":\"720p\",\"ratio\":\"16:9\",\"watermark\":false}'\n```\n\n创建返回 HTTP 202 后：\n\n```bash\ncurl --fail-with-body \"$API_ROOT/spark-media/video/TASK_ID\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\"\n```\n\n图生图和图生视频将完整的 `data:image/png;base64,...` 放进 JSON 的 `image` 字段；不要\n使用 multipart。生产中使用 UUID 等真正唯一的幂等键。\n\n创建响应的计费头是 `X-AI-Skills-Billing-Currency`、\n`X-AI-Skills-Billing-Charged`、`X-AI-Skills-Billing-Balance`。\n\nFile v2.0.0:references/IMAGE-GENERATION.md\n\n# 图片生成与编辑\n\n## 文生图\n\n`POST /api/v1/spark-media/image`\n\n| 字段 | 约束 |\n|---|---|\n| `prompt` | 必填，最多 8000 字符 |\n| `width`、`height` | 可选，各 512–4096 |\n| `count` | 可选，1–4 |\n\n## 图生图\n\n`POST /api/v1/spark-media/image/edit`\n\n除 `prompt`、`width`、`height` 外，必须提供 JSON 字段 `image`。其值是完整的 PNG、\nJPEG 或 WebP `data:` URL，例如 `data:image/png;base64,...`；不是 multipart 文件。\n解码后的图片不得超过 5 MB。\n\n两个接口都要求：\n\n```text\nAuthorization: Bearer ...\nIdempotency-Key: 每个新逻辑请求的唯一值\nContent-Type: application/json\n```\n\n保持用户要求的主体、构图、文字和风格。编辑图片时以用户提供的原图为事实来源；不要为了\n下载、改名、移动或再次展示结果而重新调用生成接口。响应中的媒体字段由上游模型决定，\n应解析并持久化实际返回内容；不要假设始终是某一种 URL 结构，也不要在聊天中输出完整\nbase64。\n\nFile v2.0.0:references/VIDEO-GENERATION.md\n\n# 视频生成与轮询\n\n## 创建任务\n\n- 文生视频：`POST /api/v1/spark-media/video`\n- 图生视频：`POST /api/v1/spark-media/video/image`\n\nJSON 参数：\n\n| 字段 | 约束 |\n|---|---|\n| `prompt` | 必填，最多 8000 字符 |\n| `duration` | 可选，`5` 或 `10` 秒 |\n| `resolution` | 可选，`480p`、`720p` 或 `1080p` |\n| `ratio` | 可选，`16:9`、`9:16` 或 `1:1` |\n| `watermark` | 可选，布尔值 |\n| `image` | 仅图生视频必填；PNG/JPEG/WebP `data:` URL，解码后最大 5 MB |\n\n两个创建接口都要求 `Idempotency-Key`，成功返回 HTTP 202、`task_id` 和初始 `status`。\n平台同一用户同一时刻只允许一个活跃视频任务；HTTP 409\n`video_task_in_progress` 表示应继续查询已有任务，不要创建并行任务。\n\n## 查询任务\n\n`GET /api/v1/spark-media/video/{task_id}`\n\n每 5–10 秒轮询一次并限制总时长。`pending`、`submitted`、`queued`、`running` 等状态\n视为进行中；`succeeded` 为成功；`failed`、`error`、`cancelled`、`canceled` 为终态失败。\n成功后读取响应中的 `video_url` 或 `result` 并立即保存需要的内容。\n\n`refunded: true` 表示失败任务的本次费用已退回。不要仅凭失败文本自行宣称退款；以该字段\n及账单记录为准。失败状态不能当作可无限重试的理由，新任务必须由用户意图或明确恢复策略\n驱动。\n\nFile v2.0.0:skill-card.md\n\n## Description:\n\nSpark Media helps agents generate and edit images, create text-to-video and image-to-video media, and query media task results through the Spark Media API.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[youteacher](https://clawhub.ai/user/youteacher)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and developers use Spark Media to create or edit visual media through a configured Spark Media API account. The skill is useful when an agent needs to prepare image or video requests, poll asynchronous video jobs, preserve returned media, and report billing information.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Prompts and supplied reference images are sent to a remote Spark Media API.\n\nMitigation: Use the skill only for media you are allowed to process externally, avoid sensitive images unless necessary, and confirm authorization before editing real-person imagery.\n\nRisk: The skill requires a dedicated API key and could expose credentials if copied into prompts, logs, or generated files.\n\nMitigation: Store SPARK_MEDIA_API_KEY in the environment, do not paste the full key in chat, and avoid writing it into code, prompts, logs, or output files.\n\nRisk: Media generation may incur account charges and video jobs are asynchronous.\n\nMitigation: Review billing headers, use idempotency keys for creation requests, and poll video tasks with bounded retries until a terminal status is reached.\n\n## Reference(s):\n\n- [Spark Media on ClawHub](https://clawhub.ai/youteacher/skills/spark-media)\n- [Spark Media homepage](https://ai-skills.open-idea.net)\n- [API Key configuration](references/API-KEY.md)\n- [Image generation and editing](references/IMAGE-GENERATION.md)\n- [Video generation and polling](references/VIDEO-GENERATION.md)\n- [HTTP request examples](references/HTTP-REQUESTS.md)\n- [Behavior, errors, and retry rules](references/BEHAVIOR-RULES.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with shell commands, JSON request examples, and returned media links or saved media files.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Requires SPARK_MEDIA_API_KEY; video jobs are asynchronous and require polling until success, failure, or timeout.]\n\n## Skill Version(s):\n\n2.0.0 (source: release evidence and package metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.0.3: 8 files, 14955 bytes\n\nFiles: references/API-KEY.md (1494b), references/BEHAVIOR-RULES.md (4631b), references/HTTP-REQUESTS.md (9205b), references/IMAGE-GENERATION.md (2915b), references/VIDEO-GENERATION.md (2476b), skill-card.md (2946b), SKILL.md (7622b), _meta.json (130b)\n\nFile v1.0.3:SKILL.md\n\n---\nname: spark-media\nversion: 1.0.3\ndescription: 提供图片与视频任务能力：输入文本生成图片，基于文字和参考图生成新图片，创建文生视频或图生视频任务，并查询视频结果。图片同步返回结果；视频采用 task_id 任务制。使用同一 SPARK_MEDIA_API_KEY 调用。\ntriggers: 生成图片, 画一张图, text to image, 文生图, 图生图, 图片改图, 参考图生成, 根据图片生成图片, 广告图, 商品海报, AI绘图, 油画风格, 水彩画, 动漫风, 国画, 科幻风, 唯美风格, 制作图片, 画图, 生成图片, 生成视频, 做个视频, 文生视频, 图生视频, 根据图片生成视频, image to video, text to video, AI视频, 短视频原型, 视频分镜, 视频任务\nmetadata:\n    {\n        \"openclaw\":\n            {\n                \"emoji\": \"🎨\",\n                \"homepage\": \"https://media.open-idea.net\",\n                \"primaryEnv\": \"SPARK_MEDIA_API_KEY\",\n                \"requires\": { \"env\": [\"SPARK_MEDIA_API_KEY\"] },\n            },\n    }\n---\n\n# Spark Media Skill 图片与视频生成技能\n\n文本生成图片、图文生成图片、文生视频与图生视频服务，基于 Spark Media 中转服务调用火山引擎媒体生成 API。Base URL: **https://media.open-idea.net/api/v1**，`Authorization: Bearer <Key>`。\n\n## Install\n\n```bash\nopenclaw skills install @youteacherasia/spark-media\n```\n\n## Setup\n\n- **`SPARK_MEDIA_API_KEY`**：[media.open-idea.net](https://media.open-idea.net) 登录后在「API Key」页创建。同一个 Key 可用于图片、图生图与视频接口。[API-KEY.md](./references/API-KEY.md)\n\n## Privacy\n\n生成图片或视频时，提示词文本与参考图片将发送至 **media.open-idea.net**，并由服务转发给上游火山引擎 API。请勿上传敏感或保密内容。\n\n## Output\n\n成功响应后，对用户展示业务结果 + 状态说明 + 计费行。\n\n### 图片结果\n\n- 根据 `data.images[]` 渲染 1-4 张图片\n- 如果 `data.mode` 为 `image_to_image`，说明结果来自文字 + 参考图生成\n- 成功响应后必须立即把 `data.images[]` 中的图片保存到本地临时文件或目标文件，再用该文件展示、下载或移动\n- 保存、展示、移动、重命名图片时，必须复用本次响应里的图片数据，**不要**再次调用 `/image` 或 `/image/edit`\n- 使用 `<img src=\"data:image/png;base64,...\">`、本地文件或下载链接展示\n- **不要**直接贴出完整 base64 字符串\n\n### 视频任务结果\n\n- 创建视频任务时，展示 `task_id` 与 `status`\n- 创建或查询成功后，如响应包含 `video_url`、`cover_url`，展示可播放视频链接与封面\n- 如果状态仍为 `submitted` / `processing`，明确提示这是异步任务，需要稍后继续查询\n\n### 计费行\n\n```text\n本次扣费: {charged} CNY, 余额: {balance} CNY\n```\n\nHTTP 头字段：`X-Mengguyu-Billing-Charged` · `X-Mengguyu-Billing-Balance` · `X-Mengguyu-Billing-Currency`\n\n说明：\n\n- 图片接口和图生图接口中的 `billing.charged` 表示本次实际扣费\n- 视频创建成功时 `billing.charged` 表示本次预扣费用；失败任务退款时，查询响应里的 `billing.charged` 可能为负数，表示本次退回金额\n\n**禁止**对用户输出：完整 JSON、完整 base64、路由说明、模型名、token、Key 等内部信息。\n\n## Usage\n\n### 生成图片\n\n```text\nPOST /image\nHeader: Idempotency-Key: <同一次用户生成请求的稳定唯一值>\nBody: { \"prompt\": \"描述文字\", \"width\": 2048, \"height\": 2048, \"style\": \"油画风格，厚涂笔触\", \"image_count\": 1 }\n```\n\n响应：`data.images[]`（1-4 张 base64 PNG）+ `data.points_used`。收到响应后先保存图片；如果用户只是询问“图片放哪里了”或要求保存到桌面，使用已保存文件或本次响应数据，不要重新生成。\n\n### 根据文字和图片生成图片\n\n```text\nPOST /image/edit\nHeader: Idempotency-Key: <同一次用户生成请求的稳定唯一值>\nMultipart Body: prompt=\"基于参考产品图生成夏季广告图\", reference_image=@product.png, width=2048, height=2048, style=\"商业广告，清爽高级\", image_count=1\n```\n\n参考图优先使用上传字段 `reference_image`；接口也支持 `image_url`。`reference_image` 和 `image_url` 二选一。multipart 是调用 Spark Media 的上传格式；Spark Media 服务端会以 JSON 调用火山，上游 `image` 字段为字符串 URL。参考图 URL 必须可被公网访问，不能使用 `127.0.0.1`、`localhost` 或内网地址。响应：`data.mode = image_to_image` + `data.images[]`（1-4 张图片数据或 URL）+ `data.points_used`。\n\n### 创建文生视频任务\n\n```text\nPOST /video\nBody: { \"prompt\": \"描述文字\", \"duration\": 5, \"resolution\": \"720p\", \"ratio\": \"16:9\" }\n```\n\n响应：`data.task_id` + `data.status` + 本次任务参数；部分上游响应可能同时包含 `data.video_url` / `data.cover_url`\n\n### 创建图生视频任务\n\n```text\nPOST /video/image\nMultipart Body: prompt=\"让参考图中的商品缓慢旋转，镜头轻微推进\", reference_image=@product.png, duration=5, resolution=\"720p\", ratio=\"16:9\"\n```\n\n也可以传 `image_url`，但 `reference_image` 和 `image_url` 只能提供一个。响应：`data.task_id` + `data.status` + `data.generation_type = image_video`。\n\n### 查询视频任务\n\n```text\nGET /video/{taskId}\n```\n\n响应：`data.status` + `data.video_url` + `data.cover_url`\n\n### Idempotency-Key 规则\n\n仅图片接口（`/image`、`/image/edit`）支持，视频接口不支持。\n\n- **每一次新的生成请求都要用新的 key**；只有在超时或网络中断后重发**完全相同**的请求体时才复用同一个 key\n- 同一个 key 配相同请求体重发：返回首次已生成的结果，`billing.charged` 为 `0`，不会重复扣费\n- 同一个 key 配**不同**请求体：返回 `409` `idempotency_key_reused`，此时应换一个新 key 重新请求\n- key 超过 191 个字符：返回 `422` `invalid_idempotency_key`\n\n### 429 的两种情况\n\n**处理方式完全相反，必须先看 `error.code` 区分。**\n\n- `error.code = daily_limit_exceeded`：**每日消费限额**。当天重试都会失败，告知用户明日再试，**不要重发**\n- 没有 `error.code`（`Too Many Attempts.`）：**每分钟请求限制**。等待几十秒后重试即可\n\n说明：\n\n- 图片接口是同步返回结果\n- 图生图接口也是同步返回结果，适合参考图改图、商品广告图、海报延展等场景\n- 视频接口是异步任务制，文生视频和图生视频都需要先创建再查询\n- 当前每个用户同一时间只允许一个进行中的视频任务；若已有任务进行中，再次创建会返回 `409`\n\n详见 [IMAGE-GENERATION.md](./references/IMAGE-GENERATION.md)、[VIDEO-GENERATION.md](./references/VIDEO-GENERATION.md) 和 [HTTP-REQUESTS.md](./references/HTTP-REQUESTS.md)。\n\n## references/\n\n| 文件                                                    | 用途                            |\n| ------------------------------------------------------- | ------------------------------- |\n| [HTTP-REQUESTS.md](./references/HTTP-REQUESTS.md)       | 图片 / 视频接口 curl 与响应示例 |\n| [IMAGE-GENERATION.md](./references/IMAGE-GENERATION.md) | 图片生成详细说明                |\n| [VIDEO-GENERATION.md](./references/VIDEO-GENERATION.md) | 视频任务详细说明                |\n| [BEHAVIOR-RULES.md](./references/BEHAVIOR-RULES.md)     | 行为规范、确认、轮询与重试      |\n| [API-KEY.md](./references/API-KEY.md)                   | Key 配置                        |\n\nFile v1.0.3:_meta.json\n\n{\n  \"ownerId\": \"kn7114n7fws0zkhdbtpvy92sp182gqge\",\n  \"slug\": \"spark-media\",\n  \"version\": \"1.0.3\",\n  \"publishedAt\": 1784116591739\n}\n\nFile v1.0.3:references/API-KEY.md\n\n# API Key 配置\n\n## 获取 API Key\n\n1. 访问 [media.open-idea.net](https://media.open-idea.net)\n2. 注册并登录账号\n3. 进入「API Key」页面创建新的 Key\n4. 复制 Key 并配置到 OpenClaw、图片 API 或视频 API 客户端\n\n## 配置环境变量\n\n```bash\nSPARK_MEDIA_API_KEY=你的APIKey\n```\n\n## 同一个 Key 可用于\n\n- OpenClaw `spark-media` Skill\n- `POST /api/v1/image` 图片生成\n- `POST /api/v1/image/edit` 图生图\n- `POST /api/v1/video` 视频任务创建\n- `POST /api/v1/video/image` 图生视频任务创建\n- `GET /api/v1/video/{taskId}` 视频任务查询\n\n## 验证 Key\n\n### 验证图片接口\n\n```bash\ncurl -X POST https://media.open-idea.net/api/v1/image \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"prompt\": \"一只在草地上打滚的柯基\",\n    \"width\": 2048,\n    \"height\": 2048\n  }'\n```\n\n### 验证视频接口\n\n```bash\ncurl -X POST https://media.open-idea.net/api/v1/video \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"prompt\": \"海边日落，镜头缓慢推进，温暖电影感\",\n    \"duration\": 5,\n    \"resolution\": \"720p\",\n    \"ratio\": \"16:9\"\n  }'\n```\n\n返回图片结果、视频任务信息或计费 / 权限错误，即表示 Key 已生效。\n\n## Key 管理\n\n- 每个用户可创建多个 API Key\n- 可在后台撤销不再使用的 Key\n- 新注册用户赠送免费额度\n- 图片与视频共用同一账号余额和同一套 Key\n\nFile v1.0.3:references/BEHAVIOR-RULES.md\n\n# 行为规范\n\n## 调用前确认\n\n- 图片生成会消耗点数，**先向用户确认**再调用 API\n- 图生图会消耗点数，并会上传或转发参考图，**先向用户确认**再调用 API\n- 图生视频会预扣视频费用，并会上传或转发参考图，**先向用户确认**再调用 API\n- 告知用户图片的预估费用，例如“生成一张 2048x2048 图片约 0.56 元”\n- 视频生成是异步任务，调用前要明确告知用户“先创建任务，再查询结果”\n- 当前每个用户同一时间只能有一个进行中的视频任务；已有任务时不要重复提交新任务\n\n## 结果展示\n\n- 图片生成成功后，直接展示图片结果与计费信息\n- 图生图成功后，直接展示图片结果、说明这是基于参考图生成，并展示计费信息\n- 图片或图生图成功后，立即把本次响应中的 `data.images[]` 保存为本地文件；用户后续询问位置、要求保存到桌面、移动或重命名时，必须复用已保存文件或本次响应数据\n- 视频任务创建成功后，先展示 `task_id` 和当前 `status`\n- 图生视频任务创建成功后，说明这是基于参考图创建的视频任务，并展示 `task_id` 和当前 `status`\n- 视频查询成功且状态为 `succeeded` 后，再展示 `video_url`、`cover_url` 或可播放结果\n- 若视频状态为 `submitted` / `processing`，要明确提示用户稍后继续查询，不要当作失败\n\n## 计费展示\n\n- 收到成功响应后，**必须**展示计费信息\n- 同时读取 HTTP 响应头和 JSON body 中的计费字段，优先使用实际响应值\n- 计费行格式：`本次扣费: {金额} CNY, 余额: {余额} CNY`\n- 图片接口和图生图接口中的 `charged` 为实际扣费\n- 视频创建成功时 `charged` 为预扣费用；视频失败退款时 `charged` 可能为负数\n\n## 错误处理\n\n| 错误类型 | 处理方式 |\n|---|---|\n| 余额不足（402） | 告知用户余额不足，引导充值 |\n| 参数错误（400 / 422） | 提示用户检查输入参数 |\n| 图生图参考图错误（422） | 提示用户只提供上传文件 `reference_image` 或 `image_url` 其中一个 |\n| 图生视频参考图错误（422） | 提示用户只提供上传文件 `reference_image` 或 `image_url` 其中一个 |\n| 视频任务冲突（409） | 告知已有任务进行中，建议等待当前任务成功或失败后再发起 |\n| **每日消费限额（429 `daily_limit_exceeded`）** | 告知今日消费已达上限，**明日再试**。重试没有意义，不要重发 |\n| **请求过于频繁（429，无 `error.code`）** | 触发了每分钟请求限制。等待几十秒后重试即可 |\n| Idempotency-Key 复用（409 `idempotency_key_reused`） | 同一个 key 被用于不同请求体，换一个新 key 重新请求即可 |\n| Idempotency-Key 过长（422 `invalid_idempotency_key`） | key 不能超过 191 个字符，改用更短的唯一值 |\n| 上游错误（502） | 告知服务暂时不可用，建议稍后重试 |\n| 网络错误 | 提示网络问题，建议重试 |\n\n## 禁止行为\n\n- **禁止**对用户暴露原始 JSON 响应\n- **禁止**透露 API Key、模型名、token 数量、内部实现\n- **禁止**在未确认前调用图片 API（避免扣费争议）\n- **禁止**在未确认前调用图生图 API（避免扣费和图片上传争议）\n- **禁止**在未确认前调用图生视频 API（避免预扣费和图片上传争议）\n- **禁止**输出完整的 base64 字符串（仅展示或提供下载）\n- **禁止**把用户上传的参考图片内容再次输出给用户\n- **禁止**在已有视频任务进行中时重复提交新视频任务\n- **禁止**为了保存、展示、下载或移动已生成图片而再次调用图片生成接口\n- **禁止**编造计费信息或视频状态，必须从响应中读取\n\n## 重试与轮询\n\n- 图片生成上游错误时，可建议用户稍后重试（间隔 5 秒以上）\n- 每一次新的图片生成请求都要使用新的 `Idempotency-Key`；只有请求超时或网络中断时，才可用相同 key 和**完全相同**的请求体重试\n- 不要把同一个 key 用于不同的提示词或参数，否则会返回 `409`；换新 key 即可\n- 图生图上游错误时，可建议用户换一张更清晰的参考图或收敛提示词后重试\n- 图生视频上游错误时，可建议用户换一张更清晰的参考图，或简化运动/镜头描述后重试\n- 视频任务创建成功后，不要立即重复提交相同任务\n- 视频任务查询建议每 5-10 秒轮询一次\n- 视频任务失败后，可建议用户调整提示词重新创建任务\n\nFile v1.0.3:references/HTTP-REQUESTS.md\n\n# 图片与视频 HTTP 请求参考\n\n## 生成图片\n\n```bash\ncurl -X POST https://media.open-idea.net/api/v1/image \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\" \\\n  -H \"Idempotency-Key: <stable-request-id>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"prompt\": \"一幅宁静的草原风景\",\n    \"width\": 2048,\n    \"height\": 2048,\n    \"style\": \"写实摄影，电影级光影\",\n    \"image_count\": 1\n  }'\n```\n\n**响应（成功 201）：**\n\n```json\n{\n    \"success\": true,\n    \"data\": {\n        \"images\": [\"<base64 PNG data>\"],\n        \"width\": 2048,\n        \"height\": 2048,\n        \"style\": \"写实摄影，电影级光影\",\n        \"image_count\": 1,\n        \"points_used\": 56\n    },\n    \"billing\": {\n        \"charged\": 0.56,\n        \"balance\": 0.44,\n        \"currency\": \"CNY\"\n    }\n}\n```\n\n**响应头：**\n\n- `X-Mengguyu-Billing-Currency: CNY`\n- `X-Mengguyu-Billing-Charged: 0.560000`\n- `X-Mengguyu-Billing-Balance: 0.440000`\n\n同一次用户生成请求请使用同一个 `Idempotency-Key`，新的生成请求要换新的 key。如果请求超时或需要重新读取结果，重复提交相同 key 和相同请求体会返回已生成结果，`billing.charged` 为 `0`，不会重复扣费。图片生成成功后应立即把 `data.images[]` 保存到文件；后续展示、下载或移动文件时不要再次调用生成接口。\n\n把同一个 key 用于不同请求体时返回 `409`：\n\n```json\n{\n  \"error\": {\n    \"message\": \"同一个 Idempotency-Key 不能用于不同的图片生成请求。\",\n    \"type\": \"idempotency_conflict\",\n    \"code\": \"idempotency_key_reused\"\n  }\n}\n```\n\n## 根据文字和图片生成图片\n\n```bash\ncurl -X POST https://media.open-idea.net/api/v1/image/edit \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\" \\\n  -H \"Idempotency-Key: <stable-request-id>\" \\\n  -F \"prompt=基于参考商品图生成一张夏季清爽风格广告图，保留商品外观，预留标题区域\" \\\n  -F \"reference_image=@product.png\" \\\n  -F \"width=2048\" \\\n  -F \"height=2048\" \\\n  -F \"style=商业广告，干净排版，高级感\" \\\n  -F \"image_count=1\"\n```\n\n也可以传 `image_url`，但 `reference_image` 和 `image_url` 只能提供一个。控制台推荐直接上传参考图片。这个 multipart 示例是客户端调用 Spark Media 的请求格式；Spark Media 服务端会再用 JSON 调用火山图片接口。\n\n注意：火山上游图生图接口使用 JSON，请求体中的 `image` 是一个字符串 URL，例如 `\"image\": \"https://...\"`，不是 multipart 字段。上传后的参考图会以 URL 形式交给火山模型下载，因此该 URL 必须是公网可访问地址，不能是 `127.0.0.1`、`localhost` 或内网 IP。线上可配置 `IMAGE_REFERENCES_DISK=s3`，把上传参考图保存到 AWS S3，再通过公开 S3 URL、CloudFront 或 `IMAGE_REFERENCES_PUBLIC_URL` 交给火山读取；本地调试时请配置 `IMAGE_REFERENCES_PUBLIC_URL` 为 ngrok、Cloudflare Tunnel、CDN 或对象存储公开地址。\n\n**响应（成功 201）：**\n\n```json\n{\n    \"success\": true,\n    \"data\": {\n        \"mode\": \"image_to_image\",\n        \"images\": [\"<base64 PNG data or image URL>\"],\n        \"width\": 2048,\n        \"height\": 2048,\n        \"style\": \"商业广告，干净排版，高级感\",\n        \"image_count\": 1,\n        \"reference_image_type\": \"upload\",\n        \"points_used\": 56\n    },\n    \"billing\": {\n        \"charged\": 0.56,\n        \"balance\": 0.44,\n        \"currency\": \"CNY\"\n    }\n}\n```\n\n## 创建视频任务\n\n```bash\ncurl -X POST https://media.open-idea.net/api/v1/video \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"prompt\": \"雨夜城市街头，镜头缓慢推进，霓虹倒影，电影感\",\n    \"duration\": 5,\n    \"resolution\": \"720p\",\n    \"ratio\": \"16:9\"\n  }'\n```\n\n**响应（成功 201）：**\n\n```json\n{\n    \"success\": true,\n    \"data\": {\n        \"task_id\": \"video_task_xxx\",\n        \"status\": \"submitted\",\n        \"duration\": 5,\n        \"resolution\": \"720p\",\n        \"ratio\": \"16:9\",\n        \"video_url\": null,\n        \"cover_url\": null\n    },\n    \"billing\": {\n        \"charged\": 6.46,\n        \"balance\": 3.54,\n        \"currency\": \"CNY\"\n    }\n}\n```\n\n## 根据图片创建视频任务\n\n```bash\ncurl -X POST https://media.open-idea.net/api/v1/video/image \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\" \\\n  -F \"prompt=让参考图中的商品缓慢旋转，镜头轻微推进，背景光线从左向右扫过\" \\\n  -F \"reference_image=@product.png\" \\\n  -F \"duration=5\" \\\n  -F \"resolution=720p\" \\\n  -F \"ratio=16:9\"\n```\n\n也可以传 `image_url`，但 `reference_image` 和 `image_url` 只能提供一个。上传后的参考图会以 URL 形式交给火山视频模型读取，因此该 URL 必须公网可访问。\n\n**响应（成功 201）：**\n\n```json\n{\n    \"success\": true,\n    \"data\": {\n        \"task_id\": \"video_task_xxx\",\n        \"status\": \"submitted\",\n        \"generation_type\": \"image_video\",\n        \"reference_image_type\": \"upload\",\n        \"reference_image_url\": \"https://example.com/reference.png\",\n        \"duration\": 5,\n        \"resolution\": \"720p\",\n        \"ratio\": \"16:9\",\n        \"video_url\": null,\n        \"cover_url\": null\n    },\n    \"billing\": {\n        \"charged\": 6.46,\n        \"balance\": 3.54,\n        \"currency\": \"CNY\"\n    }\n}\n```\n\n## 查询视频任务\n\n```bash\ncurl -X GET https://media.open-idea.net/api/v1/video/<TASK_ID> \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\"\n```\n\n**响应（成功 200）：**\n\n```json\n{\n    \"success\": true,\n    \"data\": {\n        \"task_id\": \"video_task_xxx\",\n        \"status\": \"succeeded\",\n        \"video_url\": \"https://example.com/video.mp4\",\n        \"cover_url\": \"https://example.com/cover.jpg\"\n    },\n    \"billing\": {\n        \"charged\": 0.0,\n        \"balance\": 3.54,\n        \"currency\": \"CNY\"\n    }\n}\n```\n\n## 错误响应\n\n| HTTP 状态码 | 说明                                       |\n| ----------- | ------------------------------------------ |\n| 400         | 参数错误（如 prompt 为空）                 |\n| 401         | 未授权（API Key 无效）                     |\n| 403         | API Key 权限不足                           |\n| 402         | 余额不足                                   |\n| 409         | 当前已有视频任务进行中，需等待完成后再创建；或同一个 `Idempotency-Key` 被用于不同请求体 |\n| 422         | 参数值不在支持列表中；或 `Idempotency-Key` 超过 191 个字符 |\n| 429         | 超出每日消费限额（`daily_limit_exceeded`）；或触发每分钟请求限制 |\n| 502         | 上游服务错误                               |\n\n## 429 的两种情况\n\n**429 有两个来源，处理方式完全相反，必须先看 `error.code` 区分。**\n\n每日消费限额：响应体带 `error.code = daily_limit_exceeded`。\n\n```json\n{\n  \"error\": {\n    \"message\": \"今日消费已达限额（¥100），请明日再试。\",\n    \"type\": \"daily_limit_exceeded\",\n    \"code\": \"daily_limit_exceeded\"\n  }\n}\n```\n\n这种情况**当天重试都会失败**，应告知用户明日再试，不要重发请求。图片、图生图、视频、图生视频四个接口都会检查。\n\n每分钟请求限制：Laravel 标准响应，**没有** `error.code`，`message` 为 `Too Many Attempts.`，并带 `Retry-After` 头。等待后重试即可成功。\n\n## 尺寸错误响应\n\n当图片尺寸不在支持列表中时，接口返回 `422`：\n\n```json\n{\n    \"error\": {\n        \"message\": \"当前模型仅支持 2K 及以上的推荐尺寸组合，例如 2048x2048、2304x1728、2848x1600。\",\n        \"type\": \"invalid_request_error\",\n        \"code\": \"invalid_image_size\"\n    }\n}\n```\n\n## 参考图错误响应\n\n当 `reference_image` 和 `image_url` 均未提供，或二者同时提供时，接口返回 `422`：\n\n```json\n{\n    \"error\": {\n        \"message\": \"请提供 image_url 或 reference_image，且二者只能提供一个。\",\n        \"type\": \"invalid_request_error\",\n        \"code\": \"invalid_reference_image\"\n    }\n}\n```\n\n当参考图 URL 不是公网可访问地址时，接口返回 `422`：\n\n```json\n{\n    \"error\": {\n        \"message\": \"图生图参考图地址必须是火山服务可访问的公网 URL...\",\n        \"type\": \"invalid_request_error\",\n        \"code\": \"reference_image_url_not_public\"\n    }\n}\n```\n\n## 视频任务冲突响应\n\n当同一账号已有视频任务进行中时，接口返回 `409`：\n\n```json\n{\n    \"error\": {\n        \"message\": \"当前已有视频任务进行中，请等待成功或失败后再创建新任务。\",\n        \"type\": \"conflict_error\",\n        \"code\": \"video_task_in_progress\"\n    },\n    \"data\": {\n        \"task_id\": \"video_task_xxx\",\n        \"status\": \"processing\"\n    },\n    \"billing\": {\n        \"charged\": 0.0,\n        \"balance\": 0.44,\n        \"currency\": \"CNY\"\n    }\n}\n```\n\n## 计费说明\n\n- 图片接口和图生图接口按实际点数结算，`billing.charged` 为本次实际费用\n- 视频创建成功时按预计费用预扣，`billing.charged` 为本次预扣金额\n- 视频任务失败后会退款；查询到失败状态时 `billing.charged` 可能为负数，表示本次退回金额\n- 如需统一展示余额，优先使用 JSON body 中的 `billing.balance`，并可结合响应头交叉校验\n\nFile v1.0.3:references/IMAGE-GENERATION.md\n\n# 图片生成详细说明\n\n## 文生图请求参数\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `prompt` | string | 是 | 图片描述文本，最大 2000 字符 |\n| `width` | integer | 否 | 宽度，需与支持的 2K 推荐尺寸组合一致 |\n| `height` | integer | 否 | 高度，需与支持的 2K 推荐尺寸组合一致 |\n| `style` | string | 否 | 附加到提示词中的风格描述，如\"油画风格，厚涂笔触\" |\n| `image_count` | integer | 否 | 生成数量，1-4，默认 1 |\n\n## 图生图请求参数\n\n图生图使用 `POST /image/edit`，根据文字描述和一张参考图生成新图片。它与文生图一样同步返回 `data.images[]`，并按输出图片尺寸和张数计费。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `prompt` | string | 是 | 图片修改或生成目标，最大 2000 字符 |\n| `reference_image` | file | 二选一 | multipart 上传的参考图文件 |\n| `image_url` | string | 二选一 | 参考图 URL，需为可访问的 URL；不要同时上传 `reference_image` |\n| `width` | integer | 否 | 输出宽度，默认 2048 |\n| `height` | integer | 否 | 输出高度，默认 2048 |\n| `style` | string | 否 | 附加风格描述，如\"商业广告，清爽高级\" |\n| `image_count` | integer | 否 | 生成数量，1-4，默认 1 |\n\n适合场景：\n\n- 基于商品图生成广告图、海报图、社媒封面\n- 保留参考图主体，替换背景、光影、构图或风格\n- 根据用户上传的图片生成统一视觉风格的营销素材\n\n## 推荐提示词技巧\n\n- 运用连贯的自然语言描述画面内容（主体+行为+环境等）\n- 用短词语描述画面美学（风格、色彩、光影、构图等）\n- 写出图像用途和类型，例如：PPT封面背景图、广告海报设计\n- 文字排版描述：将文字内容置于双引号内，通过指令描述文字的大小、字体、颜色、风格和位置\n- 图生图时明确说明要保留什么、改变什么，例如“保留商品外观和比例，替换为夏季海边背景，增加促销标题区域”\n\n## 尺寸与点数\n\n| 尺寸 | 点数 | 约售价（元） |\n|------|------|------|\n| 2048x2048 | 56 | 0.56 |\n| 2304x1728 | 54 | 0.54 |\n| 1728x2304 | 54 | 0.54 |\n| 2848x1600 | 61 | 0.61 |\n| 1600x2848 | 61 | 0.61 |\n| 2496x1664 | 56 | 0.56 |\n| 1664x2496 | 56 | 0.56 |\n| 3136x1344 | 57 | 0.57 |\n\n**计费公式**：点数 × 单价（元/点），默认单价 0.01 元/点。\n\n图生图按输出图片尺寸和张数使用同一计费规则。\n\n## 图片格式\n\n返回格式为 **PNG**，Base64 编码。需要时可在客户端解码保存为图片文件。\n\n## 多图生成\n\n`image_count` 参数支持 `1-4` 张图片。\n\n- 系统会按张累计计费。\n- 多图通常会比单图耗时更久。\n- 为保证稳定性，多图请求可能按张生成后再聚合返回，因此结果可能是逐张完成的。\n\nFile v1.0.3:references/VIDEO-GENERATION.md\n\n# 视频任务详细说明\n\n视频支持两种创建方式：\n\n- 文生视频：`POST /api/v1/video`\n- 图生视频：`POST /api/v1/video/image`\n\n## 请求参数\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `prompt` | string | 是 | 视频描述文本，最大 4000 字符 |\n| `duration` | integer | 否 | 时长，支持 `5`、`10`，默认 `5` |\n| `resolution` | string | 否 | 分辨率，支持 `480p`、`720p`、`1080p`，默认 `720p` |\n| `ratio` | string | 否 | 画幅比例，支持 `16:9`、`9:16`、`1:1`，默认 `16:9` |\n\n图生视频额外参数：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `reference_image` | file | 与 `image_url` 二选一 | multipart 上传的参考图片 |\n| `image_url` | string | 与 `reference_image` 二选一 | 已公网可访问的参考图片 URL |\n\n## 调用流程\n\n1. 文生视频调用 `POST /api/v1/video`；图生视频调用 `POST /api/v1/video/image`\n2. 拿到 `task_id` 与初始 `status`\n3. 继续调用 `GET /api/v1/video/{taskId}` 查询任务结果\n4. 当状态变为 `succeeded` 时，读取 `video_url` 与 `cover_url`\n\n## 任务状态\n\n| 状态 | 含义 |\n|------|------|\n| `submitted` | 任务已提交，等待处理 |\n| `processing` | 任务生成中 |\n| `succeeded` | 生成成功，可获取视频地址 |\n| `failed` | 生成失败，可调整提示词后重试 |\n\n## 使用限制\n\n- 当前每个用户同一时间只能有一个进行中的视频任务，文生视频与图生视频共用这个限制\n- 如果已有任务处于 `submitted` 或 `processing`，再次创建会返回 `409`\n- 视频是异步任务，不会像图片接口一样在一次调用中直接返回最终结果\n\n## 计费与返回\n\n- 当前视频任务创建和查询响应中会返回 `billing` 字段\n- 创建任务成功时会按预计费用预扣，`billing.charged` 为本次预扣金额\n- 如果任务最终失败，查询失败状态时会自动退款，`billing.charged` 可能为负数\n- `billing.balance` 可用于统一展示账号余额\n\n## 提示词建议\n\n- 清楚描述主体、动作、环境和镜头运动\n- 可补充画面氛围、光影、色彩和节奏\n- 如果要做短视频原型，尽量写出镜头语言，例如“推进、拉远、俯拍、跟拍”\n- 图生视频要说明参考图里的主体如何运动，例如“商品缓慢旋转、镜头轻微推进、光线扫过”\n- 失败时优先收敛提示词，不要一次堆太多主体和复杂动作\n\nFile v1.0.3:skill-card.md\n\n## Description: <br>\nSpark Media helps an agent generate images from text, generate images from text plus a reference image, create text-to-video or image-to-video tasks, and query asynchronous video results using a Spark Media API key. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[youteacherasia](https://clawhub.ai/user/youteacherasia) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nExternal users and developers use this skill to request paid image and video generation through Spark Media, including marketing images, reference-image variations, short video prototypes, and follow-up video task status checks. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Prompts and reference images are sent to Spark Media and its upstream provider. <br>\nMitigation: Avoid sensitive or confidential media and tell users before submitting prompts or reference images. <br>\nRisk: Image and video requests can spend account credit. <br>\nMitigation: Confirm billed generation requests before execution and show the charged amount and remaining balance after successful calls. <br>\nRisk: Video generation is asynchronous and can leave tasks in submitted or processing states. <br>\nMitigation: Return the task ID and current status, then query later until the task succeeds or fails. <br>\nRisk: Retrying paid or rate-limited requests incorrectly can cause confusion or duplicate work. <br>\nMitigation: Use idempotency keys for image retries, distinguish daily spending limits from per-minute rate limits, and avoid resubmitting active video tasks. <br>\n\n\n## Reference(s): <br>\n- [ClawHub skill page](https://clawhub.ai/youteacherasia/skills/spark-media) <br>\n- [Spark Media homepage](https://media.open-idea.net) <br>\n- [API key configuration](references/API-KEY.md) <br>\n- [Behavior rules](references/BEHAVIOR-RULES.md) <br>\n- [HTTP request examples](references/HTTP-REQUESTS.md) <br>\n- [Image generation details](references/IMAGE-GENERATION.md) <br>\n- [Video task details](references/VIDEO-GENERATION.md) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance] <br>\n**Output Format:** [Markdown with API request examples, status summaries, generated media links or files, and billing lines] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Image results may include PNG files or display links; video generation returns task status first and media links after the asynchronous task succeeds.] <br>\n\n## Skill Version(s): <br>\n1.0.3 (source: frontmatter and server release evidence) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nArchive v1.0.2: 8 files, 14198 bytes\n\nFiles: references/API-KEY.md (1494b), references/BEHAVIOR-RULES.md (4363b), references/HTTP-REQUESTS.md (8465b), references/IMAGE-GENERATION.md (2915b), references/VIDEO-GENERATION.md (2476b), skill-card.md (2812b), SKILL.md (7283b), _meta.json (130b)\n\nFile v1.0.2:SKILL.md\n\n---\nname: spark-media\nversion: 1.0.2\ndescription: 提供图片与视频任务能力：输入文本生成图片，基于文字和参考图生成新图片，创建文生视频或图生视频任务，并查询视频结果。图片同步返回结果；视频采用 task_id 任务制。使用同一 SPARK_MEDIA_API_KEY 调用。\ntriggers: 生成图片, 画一张图, text to image, 文生图, 图生图, 图片改图, 参考图生成, 根据图片生成图片, 广告图, 商品海报, AI绘图, 油画风格, 水彩画, 动漫风, 国画, 科幻风, 唯美风格, 制作图片, 画图, 生成图片, 生成视频, 做个视频, 文生视频, 图生视频, 根据图片生成视频, image to video, text to video, AI视频, 短视频原型, 视频分镜, 视频任务\nmetadata:\n    {\n        \"openclaw\":\n            {\n                \"emoji\": \"🎨\",\n                \"homepage\": \"https://media.open-idea.net\",\n                \"primaryEnv\": \"SPARK_MEDIA_API_KEY\",\n                \"requires\": { \"env\": [\"SPARK_MEDIA_API_KEY\"] },\n            },\n    }\n---\n\n# Spark Media Skill 图片与视频生成技能\n\n文本生成图片、图文生成图片、文生视频与图生视频服务，基于 Spark Media 中转服务调用火山引擎媒体生成 API。Base URL: **https://media.open-idea.net/api/v1**，`Authorization: Bearer <Key>`。\n\n## Install\n\n```bash\nopenclaw skills install @youteacherasia/spark-media\n```\n\n## Setup\n\n- **`SPARK_MEDIA_API_KEY`**：[media.open-idea.net](https://media.open-idea.net) 登录后在「API Key」页创建。同一个 Key 可用于图片、图生图与视频接口。[API-KEY.md](./references/API-KEY.md)\n\n## Privacy\n\n生成图片或视频时，提示词文本与参考图片将发送至 **media.open-idea.net**，并由服务转发给上游火山引擎 API。请勿上传敏感或保密内容。\n\n## Output\n\n成功响应后，对用户展示业务结果 + 状态说明 + 计费行。\n\n### 图片结果\n\n- 根据 `data.images[]` 渲染 1-4 张图片\n- 如果 `data.mode` 为 `image_to_image`，说明结果来自文字 + 参考图生成\n- 成功响应后必须立即把 `data.images[]` 中的图片保存到本地临时文件或目标文件，再用该文件展示、下载或移动\n- 保存、展示、移动、重命名图片时，必须复用本次响应里的图片数据，**不要**再次调用 `/image` 或 `/image/edit`\n- 使用 `<img src=\"data:image/png;base64,...\">`、本地文件或下载链接展示\n- **不要**直接贴出完整 base64 字符串\n\n### 视频任务结果\n\n- 创建视频任务时，展示 `task_id` 与 `status`\n- 创建或查询成功后，如响应包含 `video_url`、`cover_url`，展示可播放视频链接与封面\n- 如果状态仍为 `submitted` / `processing`，明确提示这是异步任务，需要稍后继续查询\n\n### 计费行\n\n```text\n本次扣费: {charged} CNY, 余额: {balance} CNY\n```\n\nHTTP 头字段：`X-Mengguyu-Billing-Charged` · `X-Mengguyu-Billing-Balance` · `X-Mengguyu-Billing-Currency`\n\n说明：\n\n- 图片接口和图生图接口中的 `billing.charged` 表示本次实际扣费\n- 视频创建成功时 `billing.charged` 表示本次预扣费用；失败任务退款时，查询响应里的 `billing.charged` 可能为负数，表示本次退回金额\n\n**禁止**对用户输出：完整 JSON、完整 base64、路由说明、模型名、token、Key 等内部信息。\n\n## Usage\n\n### 生成图片\n\n```text\nPOST /image\nHeader: Idempotency-Key: <同一次用户生成请求的稳定唯一值>\nBody: { \"prompt\": \"描述文字\", \"width\": 2048, \"height\": 2048, \"style\": \"油画风格，厚涂笔触\", \"image_count\": 1 }\n```\n\n响应：`data.images[]`（1-4 张 base64 PNG）+ `data.points_used`。收到响应后先保存图片；如果用户只是询问“图片放哪里了”或要求保存到桌面，使用已保存文件或本次响应数据，不要重新生成。\n\n### 根据文字和图片生成图片\n\n```text\nPOST /image/edit\nHeader: Idempotency-Key: <同一次用户生成请求的稳定唯一值>\nMultipart Body: prompt=\"基于参考产品图生成夏季广告图\", reference_image=@product.png, width=2048, height=2048, style=\"商业广告，清爽高级\", image_count=1\n```\n\n参考图优先使用上传字段 `reference_image`；接口也支持 `image_url`。`reference_image` 和 `image_url` 二选一。multipart 是调用 Spark Media 的上传格式；Spark Media 服务端会以 JSON 调用火山，上游 `image` 字段为字符串 URL。参考图 URL 必须可被公网访问，不能使用 `127.0.0.1`、`localhost` 或内网地址。响应：`data.mode = image_to_image` + `data.images[]`（1-4 张图片数据或 URL）+ `data.points_used`。\n\n### 创建文生视频任务\n\n```text\nPOST /video\nBody: { \"prompt\": \"描述文字\", \"duration\": 5, \"resolution\": \"720p\", \"ratio\": \"16:9\" }\n```\n\n响应：`data.task_id` + `data.status` + 本次任务参数；部分上游响应可能同时包含 `data.video_url` / `data.cover_url`\n\n### 创建图生视频任务\n\n```text\nPOST /video/image\nMultipart Body: prompt=\"让参考图中的商品缓慢旋转，镜头轻微推进\", reference_image=@product.png, duration=5, resolution=\"720p\", ratio=\"16:9\"\n```\n\n也可以传 `image_url`，但 `reference_image` 和 `image_url` 只能提供一个。响应：`data.task_id` + `data.status` + `data.generation_type = image_video`。\n\n### 查询视频任务\n\n```text\nGET /video/{taskId}\n```\n\n响应：`data.status` + `data.video_url` + `data.cover_url`\n\n### Idempotency-Key 规则\n\n仅图片接口（`/image`、`/image/edit`）支持，视频接口不支持。\n\n- **每一次新的生成请求都要用新的 key**；只有在超时或网络中断后重发**完全相同**的请求体时才复用同一个 key\n- 同一个 key 配相同请求体重发：返回首次已生成的结果，`billing.charged` 为 `0`，不会重复扣费\n- 同一个 key 配**不同**请求体：返回 `409` `idempotency_key_reused`，此时应换一个新 key 重新请求\n- key 超过 191 个字符：返回 `422` `invalid_idempotency_key`\n\n说明：\n\n- 图片接口是同步返回结果\n- 图生图接口也是同步返回结果，适合参考图改图、商品广告图、海报延展等场景\n- 视频接口是异步任务制，文生视频和图生视频都需要先创建再查询\n- 当前每个用户同一时间只允许一个进行中的视频任务；若已有任务进行中，再次创建会返回 `409`\n\n详见 [IMAGE-GENERATION.md](./references/IMAGE-GENERATION.md)、[VIDEO-GENERATION.md](./references/VIDEO-GENERATION.md) 和 [HTTP-REQUESTS.md](./references/HTTP-REQUESTS.md)。\n\n## references/\n\n| 文件                                                    | 用途                            |\n| ------------------------------------------------------- | ------------------------------- |\n| [HTTP-REQUESTS.md](./references/HTTP-REQUESTS.md)       | 图片 / 视频接口 curl 与响应示例 |\n| [IMAGE-GENERATION.md](./references/IMAGE-GENERATION.md) | 图片生成详细说明                |\n| [VIDEO-GENERATION.md](./references/VIDEO-GENERATION.md) | 视频任务详细说明                |\n| [BEHAVIOR-RULES.md](./references/BEHAVIOR-RULES.md)     | 行为规范、确认、轮询与重试      |\n| [API-KEY.md](./references/API-KEY.md)                   | Key 配置                        |\n\nFile v1.0.2:_meta.json\n\n{\n  \"ownerId\": \"kn7114n7fws0zkhdbtpvy92sp182gqge\",\n  \"slug\": \"spark-media\",\n  \"version\": \"1.0.2\",\n  \"publishedAt\": 1784105688691\n}\n\nFile v1.0.2:references/API-KEY.md\n\n# API Key 配置\n\n## 获取 API Key\n\n1. 访问 [media.open-idea.net](https://media.open-idea.net)\n2. 注册并登录账号\n3. 进入「API Key」页面创建新的 Key\n4. 复制 Key 并配置到 OpenClaw、图片 API 或视频 API 客户端\n\n## 配置环境变量\n\n```bash\nSPARK_MEDIA_API_KEY=你的APIKey\n```\n\n## 同一个 Key 可用于\n\n- OpenClaw `spark-media` Skill\n- `POST /api/v1/image` 图片生成\n- `POST /api/v1/image/edit` 图生图\n- `POST /api/v1/video` 视频任务创建\n- `POST /api/v1/video/image` 图生视频任务创建\n- `GET /api/v1/video/{taskId}` 视频任务查询\n\n## 验证 Key\n\n### 验证图片接口\n\n```bash\ncurl -X POST https://media.open-idea.net/api/v1/image \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"prompt\": \"一只在草地上打滚的柯基\",\n    \"width\": 2048,\n    \"height\": 2048\n  }'\n```\n\n### 验证视频接口\n\n```bash\ncurl -X POST https://media.open-idea.net/api/v1/video \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"prompt\": \"海边日落，镜头缓慢推进，温暖电影感\",\n    \"duration\": 5,\n    \"resolution\": \"720p\",\n    \"ratio\": \"16:9\"\n  }'\n```\n\n返回图片结果、视频任务信息或计费 / 权限错误，即表示 Key 已生效。\n\n## Key 管理\n\n- 每个用户可创建多个 API Key\n- 可在后台撤销不再使用的 Key\n- 新注册用户赠送免费额度\n- 图片与视频共用同一账号余额和同一套 Key\n\nFile v1.0.2:references/BEHAVIOR-RULES.md\n\n# 行为规范\n\n## 调用前确认\n\n- 图片生成会消耗点数，**先向用户确认**再调用 API\n- 图生图会消耗点数，并会上传或转发参考图，**先向用户确认**再调用 API\n- 图生视频会预扣视频费用，并会上传或转发参考图，**先向用户确认**再调用 API\n- 告知用户图片的预估费用，例如“生成一张 2048x2048 图片约 0.56 元”\n- 视频生成是异步任务，调用前要明确告知用户“先创建任务，再查询结果”\n- 当前每个用户同一时间只能有一个进行中的视频任务；已有任务时不要重复提交新任务\n\n## 结果展示\n\n- 图片生成成功后，直接展示图片结果与计费信息\n- 图生图成功后，直接展示图片结果、说明这是基于参考图生成，并展示计费信息\n- 图片或图生图成功后，立即把本次响应中的 `data.images[]` 保存为本地文件；用户后续询问位置、要求保存到桌面、移动或重命名时，必须复用已保存文件或本次响应数据\n- 视频任务创建成功后，先展示 `task_id` 和当前 `status`\n- 图生视频任务创建成功后，说明这是基于参考图创建的视频任务，并展示 `task_id` 和当前 `status`\n- 视频查询成功且状态为 `succeeded` 后，再展示 `video_url`、`cover_url` 或可播放结果\n- 若视频状态为 `submitted` / `processing`，要明确提示用户稍后继续查询，不要当作失败\n\n## 计费展示\n\n- 收到成功响应后，**必须**展示计费信息\n- 同时读取 HTTP 响应头和 JSON body 中的计费字段，优先使用实际响应值\n- 计费行格式：`本次扣费: {金额} CNY, 余额: {余额} CNY`\n- 图片接口和图生图接口中的 `charged` 为实际扣费\n- 视频创建成功时 `charged` 为预扣费用；视频失败退款时 `charged` 可能为负数\n\n## 错误处理\n\n| 错误类型 | 处理方式 |\n|---|---|\n| 余额不足（402） | 告知用户余额不足，引导充值 |\n| 参数错误（400 / 422） | 提示用户检查输入参数 |\n| 图生图参考图错误（422） | 提示用户只提供上传文件 `reference_image` 或 `image_url` 其中一个 |\n| 图生视频参考图错误（422） | 提示用户只提供上传文件 `reference_image` 或 `image_url` 其中一个 |\n| 视频任务冲突（409） | 告知已有任务进行中，建议等待当前任务成功或失败后再发起 |\n| Idempotency-Key 复用（409 `idempotency_key_reused`） | 同一个 key 被用于不同请求体，换一个新 key 重新请求即可 |\n| Idempotency-Key 过长（422 `invalid_idempotency_key`） | key 不能超过 191 个字符，改用更短的唯一值 |\n| 上游错误（502） | 告知服务暂时不可用，建议稍后重试 |\n| 网络错误 | 提示网络问题，建议重试 |\n\n## 禁止行为\n\n- **禁止**对用户暴露原始 JSON 响应\n- **禁止**透露 API Key、模型名、token 数量、内部实现\n- **禁止**在未确认前调用图片 API（避免扣费争议）\n- **禁止**在未确认前调用图生图 API（避免扣费和图片上传争议）\n- **禁止**在未确认前调用图生视频 API（避免预扣费和图片上传争议）\n- **禁止**输出完整的 base64 字符串（仅展示或提供下载）\n- **禁止**把用户上传的参考图片内容再次输出给用户\n- **禁止**在已有视频任务进行中时重复提交新视频任务\n- **禁止**为了保存、展示、下载或移动已生成图片而再次调用图片生成接口\n- **禁止**编造计费信息或视频状态，必须从响应中读取\n\n## 重试与轮询\n\n- 图片生成上游错误时，可建议用户稍后重试（间隔 5 秒以上）\n- 每一次新的图片生成请求都要使用新的 `Idempotency-Key`；只有请求超时或网络中断时，才可用相同 key 和**完全相同**的请求体重试\n- 不要把同一个 key 用于不同的提示词或参数，否则会返回 `409`；换新 key 即可\n- 图生图上游错误时，可建议用户换一张更清晰的参考图或收敛提示词后重试\n- 图生视频上游错误时，可建议用户换一张更清晰的参考图，或简化运动/镜头描述后重试\n- 视频任务创建成功后，不要立即重复提交相同任务\n- 视频任务查询建议每 5-10 秒轮询一次\n- 视频任务失败后，可建议用户调整提示词重新创建任务\n\nFile v1.0.2:references/HTTP-REQUESTS.md\n\n# 图片与视频 HTTP 请求参考\n\n## 生成图片\n\n```bash\ncurl -X POST https://media.open-idea.net/api/v1/image \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\" \\\n  -H \"Idempotency-Key: <stable-request-id>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"prompt\": \"一幅宁静的草原风景\",\n    \"width\": 2048,\n    \"height\": 2048,\n    \"style\": \"写实摄影，电影级光影\",\n    \"image_count\": 1\n  }'\n```\n\n**响应（成功 201）：**\n\n```json\n{\n    \"success\": true,\n    \"data\": {\n        \"images\": [\"<base64 PNG data>\"],\n        \"width\": 2048,\n        \"height\": 2048,\n        \"style\": \"写实摄影，电影级光影\",\n        \"image_count\": 1,\n        \"points_used\": 56\n    },\n    \"billing\": {\n        \"charged\": 0.56,\n        \"balance\": 0.44,\n        \"currency\": \"CNY\"\n    }\n}\n```\n\n**响应头：**\n\n- `X-Mengguyu-Billing-Currency: CNY`\n- `X-Mengguyu-Billing-Charged: 0.560000`\n- `X-Mengguyu-Billing-Balance: 0.440000`\n\n同一次用户生成请求请使用同一个 `Idempotency-Key`，新的生成请求要换新的 key。如果请求超时或需要重新读取结果，重复提交相同 key 和相同请求体会返回已生成结果，`billing.charged` 为 `0`，不会重复扣费。图片生成成功后应立即把 `data.images[]` 保存到文件；后续展示、下载或移动文件时不要再次调用生成接口。\n\n把同一个 key 用于不同请求体时返回 `409`：\n\n```json\n{\n  \"error\": {\n    \"message\": \"同一个 Idempotency-Key 不能用于不同的图片生成请求。\",\n    \"type\": \"idempotency_conflict\",\n    \"code\": \"idempotency_key_reused\"\n  }\n}\n```\n\n## 根据文字和图片生成图片\n\n```bash\ncurl -X POST https://media.open-idea.net/api/v1/image/edit \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\" \\\n  -H \"Idempotency-Key: <stable-request-id>\" \\\n  -F \"prompt=基于参考商品图生成一张夏季清爽风格广告图，保留商品外观，预留标题区域\" \\\n  -F \"reference_image=@product.png\" \\\n  -F \"width=2048\" \\\n  -F \"height=2048\" \\\n  -F \"style=商业广告，干净排版，高级感\" \\\n  -F \"image_count=1\"\n```\n\n也可以传 `image_url`，但 `reference_image` 和 `image_url` 只能提供一个。控制台推荐直接上传参考图片。这个 multipart 示例是客户端调用 Spark Media 的请求格式；Spark Media 服务端会再用 JSON 调用火山图片接口。\n\n注意：火山上游图生图接口使用 JSON，请求体中的 `image` 是一个字符串 URL，例如 `\"image\": \"https://...\"`，不是 multipart 字段。上传后的参考图会以 URL 形式交给火山模型下载，因此该 URL 必须是公网可访问地址，不能是 `127.0.0.1`、`localhost` 或内网 IP。线上可配置 `IMAGE_REFERENCES_DISK=s3`，把上传参考图保存到 AWS S3，再通过公开 S3 URL、CloudFront 或 `IMAGE_REFERENCES_PUBLIC_URL` 交给火山读取；本地调试时请配置 `IMAGE_REFERENCES_PUBLIC_URL` 为 ngrok、Cloudflare Tunnel、CDN 或对象存储公开地址。\n\n**响应（成功 201）：**\n\n```json\n{\n    \"success\": true,\n    \"data\": {\n        \"mode\": \"image_to_image\",\n        \"images\": [\"<base64 PNG data or image URL>\"],\n        \"width\": 2048,\n        \"height\": 2048,\n        \"style\": \"商业广告，干净排版，高级感\",\n        \"image_count\": 1,\n        \"reference_image_type\": \"upload\",\n        \"points_used\": 56\n    },\n    \"billing\": {\n        \"charged\": 0.56,\n        \"balance\": 0.44,\n        \"currency\": \"CNY\"\n    }\n}\n```\n\n## 创建视频任务\n\n```bash\ncurl -X POST https://media.open-idea.net/api/v1/video \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"prompt\": \"雨夜城市街头，镜头缓慢推进，霓虹倒影，电影感\",\n    \"duration\": 5,\n    \"resolution\": \"720p\",\n    \"ratio\": \"16:9\"\n  }'\n```\n\n**响应（成功 201）：**\n\n```json\n{\n    \"success\": true,\n    \"data\": {\n        \"task_id\": \"video_task_xxx\",\n        \"status\": \"submitted\",\n        \"duration\": 5,\n        \"resolution\": \"720p\",\n        \"ratio\": \"16:9\",\n        \"video_url\": null,\n        \"cover_url\": null\n    },\n    \"billing\": {\n        \"charged\": 6.46,\n        \"balance\": 3.54,\n        \"currency\": \"CNY\"\n    }\n}\n```\n\n## 根据图片创建视频任务\n\n```bash\ncurl -X POST https://media.open-idea.net/api/v1/video/image \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\" \\\n  -F \"prompt=让参考图中的商品缓慢旋转，镜头轻微推进，背景光线从左向右扫过\" \\\n  -F \"reference_image=@product.png\" \\\n  -F \"duration=5\" \\\n  -F \"resolution=720p\" \\\n  -F \"ratio=16:9\"\n```\n\n也可以传 `image_url`，但 `reference_image` 和 `image_url` 只能提供一个。上传后的参考图会以 URL 形式交给火山视频模型读取，因此该 URL 必须公网可访问。\n\n**响应（成功 201）：**\n\n```json\n{\n    \"success\": true,\n    \"data\": {\n        \"task_id\": \"video_task_xxx\",\n        \"status\": \"submitted\",\n        \"generation_type\": \"image_video\",\n        \"reference_image_type\": \"upload\",\n        \"reference_image_url\": \"https://example.com/reference.png\",\n        \"duration\": 5,\n        \"resolution\": \"720p\",\n        \"ratio\": \"16:9\",\n        \"video_url\": null,\n        \"cover_url\": null\n    },\n    \"billing\": {\n        \"charged\": 6.46,\n        \"balance\": 3.54,\n        \"currency\": \"CNY\"\n    }\n}\n```\n\n## 查询视频任务\n\n```bash\ncurl -X GET https://media.open-idea.net/api/v1/video/<TASK_ID> \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\"\n```\n\n**响应（成功 200）：**\n\n```json\n{\n    \"success\": true,\n    \"data\": {\n        \"task_id\": \"video_task_xxx\",\n        \"status\": \"succeeded\",\n        \"video_url\": \"https://example.com/video.mp4\",\n        \"cover_url\": \"https://example.com/cover.jpg\"\n    },\n    \"billing\": {\n        \"charged\": 0.0,\n        \"balance\": 3.54,\n        \"currency\": \"CNY\"\n    }\n}\n```\n\n## 错误响应\n\n| HTTP 状态码 | 说明                                       |\n| ----------- | ------------------------------------------ |\n| 400         | 参数错误（如 prompt 为空）                 |\n| 401         | 未授权（API Key 无效）                     |\n| 403         | API Key 权限不足                           |\n| 402         | 余额不足                                   |\n| 409         | 当前已有视频任务进行中，需等待完成后再创建；或同一个 `Idempotency-Key` 被用于不同请求体 |\n| 422         | 参数值不在支持列表中；或 `Idempotency-Key` 超过 191 个字符 |\n| 429         | 超出日限额                                 |\n| 502         | 上游服务错误                               |\n\n## 尺寸错误响应\n\n当图片尺寸不在支持列表中时，接口返回 `422`：\n\n```json\n{\n    \"error\": {\n        \"message\": \"当前模型仅支持 2K 及以上的推荐尺寸组合，例如 2048x2048、2304x1728、2848x1600。\",\n        \"type\": \"invalid_request_error\",\n        \"code\": \"invalid_image_size\"\n    }\n}\n```\n\n## 参考图错误响应\n\n当 `reference_image` 和 `image_url` 均未提供，或二者同时提供时，接口返回 `422`：\n\n```json\n{\n    \"error\": {\n        \"message\": \"请提供 image_url 或 reference_image，且二者只能提供一个。\",\n        \"type\": \"invalid_request_error\",\n        \"code\": \"invalid_reference_image\"\n    }\n}\n```\n\n当参考图 URL 不是公网可访问地址时，接口返回 `422`：\n\n```json\n{\n    \"error\": {\n        \"message\": \"图生图参考图地址必须是火山服务可访问的公网 URL...\",\n        \"type\": \"invalid_request_error\",\n        \"code\": \"reference_image_url_not_public\"\n    }\n}\n```\n\n## 视频任务冲突响应\n\n当同一账号已有视频任务进行中时，接口返回 `409`：\n\n```json\n{\n    \"error\": {\n        \"message\": \"当前已有视频任务进行中，请等待成功或失败后再创建新任务。\",\n        \"type\": \"conflict_error\",\n        \"code\": \"video_task_in_progress\"\n    },\n    \"data\": {\n        \"task_id\": \"video_task_xxx\",\n        \"status\": \"processing\"\n    },\n    \"billing\": {\n        \"charged\": 0.0,\n        \"balance\": 0.44,\n        \"currency\": \"CNY\"\n    }\n}\n```\n\n## 计费说明\n\n- 图片接口和图生图接口按实际点数结算，`billing.charged` 为本次实际费用\n- 视频创建成功时按预计费用预扣，`billing.charged` 为本次预扣金额\n- 视频任务失败后会退款；查询到失败状态时 `billing.charged` 可能为负数，表示本次退回金额\n- 如需统一展示余额，优先使用 JSON body 中的 `billing.balance`，并可结合响应头交叉校验\n\nFile v1.0.2:references/IMAGE-GENERATION.md\n\n# 图片生成详细说明\n\n## 文生图请求参数\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `prompt` | string | 是 | 图片描述文本，最大 2000 字符 |\n| `width` | integer | 否 | 宽度，需与支持的 2K 推荐尺寸组合一致 |\n| `height` | integer | 否 | 高度，需与支持的 2K 推荐尺寸组合一致 |\n| `style` | string | 否 | 附加到提示词中的风格描述，如\"油画风格，厚涂笔触\" |\n| `image_count` | integer | 否 | 生成数量，1-4，默认 1 |\n\n## 图生图请求参数\n\n图生图使用 `POST /image/edit`，根据文字描述和一张参考图生成新图片。它与文生图一样同步返回 `data.images[]`，并按输出图片尺寸和张数计费。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `prompt` | string | 是 | 图片修改或生成目标，最大 2000 字符 |\n| `reference_image` | file | 二选一 | multipart 上传的参考图文件 |\n| `image_url` | string | 二选一 | 参考图 URL，需为可访问的 URL；不要同时上传 `reference_image` |\n| `width` | integer | 否 | 输出宽度，默认 2048 |\n| `height` | integer | 否 | 输出高度，默认 2048 |\n| `style` | string | 否 | 附加风格描述，如\"商业广告，清爽高级\" |\n| `image_count` | integer | 否 | 生成数量，1-4，默认 1 |\n\n适合场景：\n\n- 基于商品图生成广告图、海报图、社媒封面\n- 保留参考图主体，替换背景、光影、构图或风格\n- 根据用户上传的图片生成统一视觉风格的营销素材\n\n## 推荐提示词技巧\n\n- 运用连贯的自然语言描述画面内容（主体+行为+环境等）\n- 用短词语描述画面美学（风格、色彩、光影、构图等）\n- 写出图像用途和类型，例如：PPT封面背景图、广告海报设计\n- 文字排版描述：将文字内容置于双引号内，通过指令描述文字的大小、字体、颜色、风格和位置\n- 图生图时明确说明要保留什么、改变什么，例如“保留商品外观和比例，替换为夏季海边背景，增加促销标题区域”\n\n## 尺寸与点数\n\n| 尺寸 | 点数 | 约售价（元） |\n|------|------|------|\n| 2048x2048 | 56 | 0.56 |\n| 2304x1728 | 54 | 0.54 |\n| 1728x2304 | 54 | 0.54 |\n| 2848x1600 | 61 | 0.61 |\n| 1600x2848 | 61 | 0.61 |\n| 2496x1664 | 56 | 0.56 |\n| 1664x2496 | 56 | 0.56 |\n| 3136x1344 | 57 | 0.57 |\n\n**计费公式**：点数 × 单价（元/点），默认单价 0.01 元/点。\n\n图生图按输出图片尺寸和张数使用同一计费规则。\n\n## 图片格式\n\n返回格式为 **PNG**，Base64 编码。需要时可在客户端解码保存为图片文件。\n\n## 多图生成\n\n`image_count` 参数支持 `1-4` 张图片。\n\n- 系统会按张累计计费。\n- 多图通常会比单图耗时更久。\n- 为保证稳定性，多图请求可能按张生成后再聚合返回，因此结果可能是逐张完成的。\n\nFile v1.0.2:references/VIDEO-GENERATION.md\n\n# 视频任务详细说明\n\n视频支持两种创建方式：\n\n- 文生视频：`POST /api/v1/video`\n- 图生视频：`POST /api/v1/video/image`\n\n## 请求参数\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `prompt` | string | 是 | 视频描述文本，最大 4000 字符 |\n| `duration` | integer | 否 | 时长，支持 `5`、`10`，默认 `5` |\n| `resolution` | string | 否 | 分辨率，支持 `480p`、`720p`、`1080p`，默认 `720p` |\n| `ratio` | string | 否 | 画幅比例，支持 `16:9`、`9:16`、`1:1`，默认 `16:9` |\n\n图生视频额外参数：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `reference_image` | file | 与 `image_url` 二选一 | multipart 上传的参考图片 |\n| `image_url` | string | 与 `reference_image` 二选一 | 已公网可访问的参考图片 URL |\n\n## 调用流程\n\n1. 文生视频调用 `POST /api/v1/video`；图生视频调用 `POST /api/v1/video/image`\n2. 拿到 `task_id` 与初始 `status`\n3. 继续调用 `GET /api/v1/video/{taskId}` 查询任务结果\n4. 当状态变为 `succeeded` 时，读取 `video_url` 与 `cover_url`\n\n## 任务状态\n\n| 状态 | 含义 |\n|------|------|\n| `submitted` | 任务已提交，等待处理 |\n| `processing` | 任务生成中 |\n| `succeeded` | 生成成功，可获取视频地址 |\n| `failed` | 生成失败，可调整提示词后重试 |\n\n## 使用限制\n\n- 当前每个用户同一时间只能有一个进行中的视频任务，文生视频与图生视频共用这个限制\n- 如果已有任务处于 `submitted` 或 `processing`，再次创建会返回 `409`\n- 视频是异步任务，不会像图片接口一样在一次调用中直接返回最终结果\n\n## 计费与返回\n\n- 当前视频任务创建和查询响应中会返回 `billing` 字段\n- 创建任务成功时会按预计费用预扣，`billing.charged` 为本次预扣金额\n- 如果任务最终失败，查询失败状态时会自动退款，`billing.charged` 可能为负数\n- `billing.balance` 可用于统一展示账号余额\n\n## 提示词建议\n\n- 清楚描述主体、动作、环境和镜头运动\n- 可补充画面氛围、光影、色彩和节奏\n- 如果要做短视频原型，尽量写出镜头语言，例如“推进、拉远、俯拍、跟拍”\n- 图生视频要说明参考图里的主体如何运动，例如“商品缓慢旋转、镜头轻微推进、光线扫过”\n- 失败时优先收敛提示词，不要一次堆太多主体和复杂动作\n\nFile v1.0.2:skill-card.md\n\n## Description: <br>\nSpark Media lets agents generate images from text, create new images from text plus a reference image, create text-to-video or image-to-video tasks, and query asynchronous video results through the Spark Media API. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[youteacherasia](https://clawhub.ai/user/youteacherasia) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nExternal users and developers use this skill to create marketing images, edited reference-image outputs, short video tasks, and video status checks through a paid Spark Media API key. It is suited for media-generation workflows where prompts and reference images may be sent to media.open-idea.net and its upstream provider. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Prompts and reference images are sent to media.open-idea.net and its upstream provider. <br>\nMitigation: Confirm user intent before generation calls and avoid sending sensitive or confidential prompts or images. <br>\nRisk: SPARK_MEDIA_API_KEY can spend account balance for generated media calls. <br>\nMitigation: Store the key only as a secret environment variable, do not expose it in outputs, and show billing information after successful paid calls. <br>\nRisk: Video generation is asynchronous and each user may have only one active video task at a time. <br>\nMitigation: Return the task ID and status, poll later for completion, and avoid submitting duplicate video tasks while one is still processing. <br>\n\n\n## Reference(s): <br>\n- [Spark Media homepage](https://media.open-idea.net) <br>\n- [Spark Media ClawHub page](https://clawhub.ai/youteacherasia/skills/spark-media) <br>\n- [API Key](references/API-KEY.md) <br>\n- [HTTP Requests](references/HTTP-REQUESTS.md) <br>\n- [Image Generation](references/IMAGE-GENERATION.md) <br>\n- [Video Generation](references/VIDEO-GENERATION.md) <br>\n- [Behavior Rules](references/BEHAVIOR-RULES.md) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance] <br>\n**Output Format:** [Markdown guidance with inline HTTP examples, local file handling instructions, and media result links or files] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Image calls return PNG media synchronously; video calls return task IDs and require later status queries.] <br>\n\n## Skill Version(s): <br>\n1.0.2 (source: frontmatter and server release evidence) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>","readmeExcerpt":"Skill: spark-media Owner: youteacher Summary: 使用场景: 用户明确希望通过 AI Skills 平台 API 生成图片、编辑参考图、文生视频、图生视频、制作短视频或查询媒体任务。 Tags: latest:2.5.2 Version history: v2.5.2 | 2026-09-18T09:08:40.827Z | auto - Updated to version 2.5.2. - SKILL.md: Clarified usage scenarios, added license field, and updated packageVersion metadata. - Added completion standards on async operation handling, error retries, and multi-step/multi-file reques","codeSnippets":[],"executableExamples":[{"language":"sh","snippet":"openclaw config set env.SPARK_MEDIA_API_KEY \"你的平台APIKey\"\nopenclaw gateway restart"},{"language":"bash","snippet":"export SPARK_MEDIA_API_KEY=\"ais_...\"\nexport AI_SKILLS_API_URL=\"https://ai-skills.open-idea.net\" # 可选"},{"language":"text","snippet":"Authorization: Bearer $SPARK_MEDIA_API_KEY"},{"language":"bash","snippet":"curl --fail-with-body \"$API_ROOT/spark-media/image\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: image-uuid-001\" \\\n  -d '{\"prompt\":\"雪山下的藏式村庄，电影感光线\",\"width\":1024,\"height\":1024,\"count\":1}'"},{"language":"bash","snippet":"API_ROOT=\"${AI_SKILLS_API_URL:-https://ai-skills.open-idea.net}/api/v1\"\n\ncurl --fail-with-body \"$API_ROOT/spark-media/image\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: image-uuid-001\" \\\n  -d '{\"prompt\":\"雪山下的藏式村庄，电影感光线\",\"width\":1024,\"height\":1024,\"count\":1}'"},{"language":"bash","snippet":"curl --fail-with-body \"$API_ROOT/spark-media/video\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: video-uuid-001\" \\\n  -d '{\"prompt\":\"云层缓慢掠过雪山\",\"duration\":5,\"resolution\":\"720p\",\"ratio\":\"16:9\",\"watermark\":false}'"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: spark-media\ndescription: \"使用场景: 用户明确希望通过 AI Skills 平台 API 生成图片、编辑参考图、文生视频、图生视频、制作短视频或查询媒体任务。\"\nlicense: MIT-0\nmetadata:\n    {\n        \"packageVersion\": \"2.5.2\",\n        \"openclaw\":\n            {\n                \"emoji\": \"✨\",\n                \"homepage\": \"https://ai-skills.open-idea.net\",\n                \"primaryEnv\": \"SPARK_MEDIA_API_KEY\",\n                \"requires\": { \"env\": [\"SPARK_MEDIA_API_KEY\"] },\n            },\n    }\n---\n\n# Spark 媒体\n\n## Skill 简介\n\nSpark Media 用于根据文字生成图片和视频、基于参考图进行图片或视频创作，并查询媒体任务进度与结果，适合广告图、商品图、海报和短视频素材制作。\n\n## 平台入口与注册\n\n1. 打开 [AI Skills 平台](https://ai-skills.open-idea.net/)，新用户可直接进入 [注册页面](https://ai-skills.open-idea.net/register)，已有账号进入 [登录页面](https://ai-skills.open-idea.net/login)。\n2. 登录后进入 [产品管理](https://ai-skills.open-idea.net/dashboard/products) 开通本 Skill，再到 [API 密钥管理](https://ai-skills.open-idea.net/dashboard/keys) 创建密钥。\n\n## Skill 安装与配置\n\n1. 在 [API 密钥管理](https://ai-skills.open-idea.net/dashboard/keys)中选择已开通的产品，创建并复制 API 密钥。\n2. 在 OpenClaw 中安装本 Skill。\n3. 将复制的密钥配置到本 Skill 的 API 密钥环境变量，然后重启 Gateway：\n\n```sh\nopenclaw config set env.SPARK_MEDIA_API_KEY \"你的平台APIKey\"\nopenclaw gateway restart\n```\n\n## 完成标准\n\n- 异步操作提交后持续轮询任务状态，直到成功或失败的终态再汇报；不要在 pending/processing 中途停下征求许可。\n- 用户已确认的处理范围内，遇 429/503 按参考文档以原幂等键退避重试（不产生额外扣费），恢复后继续，无需再次确认。\n- 一次请求涉及多个文件或多个步骤时，全部处理完再汇报；部分失败要逐项说明哪些成功、哪些失败及原因。\n\n## 参考资料\n\n- [API 密钥配置](https://ai-skills.open-idea.net/skill-docs/spark-media/API-KEY.md)\n- [图片生成与编辑](https://ai-skills.open-idea.net/skill-docs/spark-media/IMAGE-GENERATION.md)\n- [视频生成与轮询](https://ai-skills.open-idea.net/skill-docs/spark-media/VIDEO-GENERATION.md)\n- [HTTP 请求示例](https://ai-skills.open-idea.net/skill-docs/spark-media/HTTP-REQUESTS.md)\n- [行为、错误与重试规则](https://ai-skills.open-idea.net/skill-docs/spark-media/BEHAVIOR-RULES.md)"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7114n7fws0zkhdbtpvy92sp182gqge\",\n  \"slug\": \"spark-media\",\n  \"version\": \"2.5.2\",\n  \"publishedAt\": 1789722520827\n}"},{"path":"references/API-KEY.md","content":"# API 密钥配置\n\n\n```bash\nexport SPARK_MEDIA_API_KEY=\"ais_...\"\nexport AI_SKILLS_API_URL=\"https://ai-skills.open-idea.net\" # 可选\n```\n\n请求根地址为 `${AI_SKILLS_API_URL:-https://ai-skills.open-idea.net}/api/v1`。\n\n```text\nAuthorization: Bearer $SPARK_MEDIA_API_KEY\n```\n\n密钥仅绑定 Spark Media，不能跨 Skill 使用。不要要求用户在聊天中粘贴完整密钥，也不要\n将密钥写入代码、提示词、日志或生成文件。常见鉴权错误包括 `invalid_api_key`、\n`key_expired`、`key_revoked`、`skill_not_active`、`user_skill_suspended` 和\n`account_suspended`。"},{"path":"references/BEHAVIOR-RULES.md","content":"# 行为、错误与重试规则\n\n## 安全与质量\n\n- 不生成违法、有害或侵犯隐私的内容；涉及真人敏感编辑时先核实授权。\n- 图像输入只上传完成任务所需内容，敏感图片上传前取得同意。\n- 结果字段缺失、解码失败或任务状态未知时明确报告异常，不伪造媒体。\n- 保存、移动、重命名或再次展示现有结果时禁止重新生成。\n\n## 幂等与错误\n\n- 四个创建接口都必须有 `Idempotency-Key`；同一请求重试复用原值，参数变化才换新值。\n- `validation_failed`（验证失败）：修正尺寸、格式、时长、画幅或字段。\n- `insufficient_balance`（余额不足）：提示充值，不自动创建新任务。\n- `rate_limited`（受到速率限制）：遵循 `Retry-After` 或有限指数退避。\n- `upstream_unavailable`（上游服务不可用）：短暂退避后复用原幂等键重试，限制次数。\n- `idempotency_in_progress`（幂等请求处理中）：等待原请求，不换密钥并发提交。\n- `idempotency_indeterminate`（幂等结果不确定）：停止自动重试并核对原请求、任务和账单。\n- `video_task_in_progress`（视频任务处理中）：查询现有任务，不能绕过单活跃任务限制。\n\n幂等重放返回首次响应与首次计费头。统一计费头为\n`X-AI-Skills-Billing-Currency`、`X-AI-Skills-Billing-Charged`、\n`X-AI-Skills-Billing-Balance`。"},{"path":"references/HTTP-REQUESTS.md","content":"# HTTP 请求示例\n\n```bash\nAPI_ROOT=\"${AI_SKILLS_API_URL:-https://ai-skills.open-idea.net}/api/v1\"\n\ncurl --fail-with-body \"$API_ROOT/spark-media/image\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: image-uuid-001\" \\\n  -d '{\"prompt\":\"雪山下的藏式村庄，电影感光线\",\"width\":1024,\"height\":1024,\"count\":1}'\n```\n\n```bash\ncurl --fail-with-body \"$API_ROOT/spark-media/video\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: video-uuid-001\" \\\n  -d '{\"prompt\":\"云层缓慢掠过雪山\",\"duration\":5,\"resolution\":\"720p\",\"ratio\":\"16:9\",\"watermark\":false}'\n```\n\n创建返回 HTTP 202 后：\n\n```bash\ncurl --fail-with-body \"$API_ROOT/spark-media/video/TASK_ID\" \\\n  -H \"Authorization: Bearer $SPARK_MEDIA_API_KEY\"\n```\n\n图生图和图生视频将完整的 `data:image/png;base64,...` 放进 JSON 的 `image` 字段；不要\n使用 multipart。生产中使用 UUID 等真正唯一的幂等键。\n\n创建响应的计费头是 `X-AI-Skills-Billing-Currency`、\n`X-AI-Skills-Billing-Charged`、`X-AI-Skills-Billing-Balance`。"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"使用场景: 用户明确希望通过 AI Skills 平台 API 生成图片、编辑参考图、文生视频、图生视频、制作短视频或查询媒体任务。 Skill: spark-media Owner: youteacher Summary: 使用场景: 用户明确希望通过 AI Skills 平台 API 生成图片、编辑参考图、文生视频、图生视频、制作短视频或查询媒体任务。 Tags: latest:2.5.2 Version history: v2.5.2 | 2026-09-18T09:08:40.827Z | auto - Updated to version 2.5.2. - SKILL.md: Clarified usage scenarios, added license field, and updated packageVersion metadata. - Added completion standards on async operation handling, error retries, and multi-step/multi-file reques","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":583,"uniquenessScore":59,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T05:41:46.134Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T05:41:46.134Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T07:41:59.889Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}