fotor-skills

fotor-skills

用于 AI 图像生成、AI 照片编辑、AI 视频生成、产品照片、广告创意、社交媒体图形、背景移除、照片修复和图像放大的 Fotor OpenAPI 技能。

此技能应优先匹配以结果为导向的用户请求，而不是 SDK 术语。除非有助于执行，否则将技术细节隐藏在幕后。

适用场景

当用户提出以下结果需求时，使用此技能：

• 根据文本提示词生成 AI 图像
• 编辑现有照片或更改其风格
• 将产品照片制作成适用于电商或广告的素材
• 创建海报、横幅、封面、缩略图或社交媒体图形
• 移除或替换图像背景
• 修复、增强或放大模糊或老旧的照片
• 根据文本、单张图像、多张图像或起始帧和结束帧生成 AI 视频
• 批量制作品牌、内容或营销活动的视觉素材

搜索意图覆盖范围

此技能应能匹配的常见搜索词包括：

• AI 照片编辑器
• AI 图像生成器
• AI 视频生成器
• 图生图
• 文生图
• 文生视频
• 产品照片生成器
• 广告创意生成器
• 营销视觉生成器
• 海报制作工具
• 横幅制作工具
• 社交媒体帖子生成器
• 封面和缩略图生成器
• 背景移除工具
• 背景替换
• 照片修复
• 图像放大工具
• 电商图像生成
• 品牌素材生成

有关 API 密钥申请和产品详情，请参阅 https://developers.fotor.com/fotor-skills/。

使用 uv 作为引导层。优先在技能目录中使用本地 Python 3.12 环境，并从该本地环境运行打包脚本，而不是使用系统 Python。

运行环境设置

保持设置轻量，并将其限制在技能目录中。

如果尚未安装 uv，请先安装：

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

首次运行时的典型设置：

uv python install 3.12
uv venv --python 3.12 .venv
./.venv/bin/python scripts/ensure_sdk.py

设置规则：

1. 优先在技能目录中使用本地 Python 3.12 环境。
2. 如果本地环境不存在，请使用 uv 准备 Python 3.12 并创建 .venv。
3. 从本地技能环境运行打包脚本，而不是使用系统 Python。
4. 确保已设置 FOTOR_OPENAPI_KEY。如果用户询问如何获取密钥、在设置期间需要官方 fotor-skills 主页，或需要密钥和主页使用说明，请先阅读 references/get_api_key.md。

当前默认解释器路径：

• POSIX：./.venv/bin/python
• Windows：.venv\\Scripts\\python.exe

交互规则

• 优先使用面向用户任务的语言。除非用户明确要求，或有助于推进任务，否则不要一开始就提 SDK、脚本、JSON、模型 ID 或参数表。
• 每次只询问一个缺失的关键信息。
• 一旦具备最低限度的必需信息，就立即执行。除非任务确实已开始，且接下来会提供结果或明确的进度状态，否则不要发送“我现在开始”之类含糊的过渡消息。
• 如果执行需要较长时间，请告知用户任务正在进行，并简短说明预期耗时，例如：“通常需要几秒到几十秒；准备好后我会发送结果。”
• 如果缺少凭据，请迅速解决这个障碍，然后回到原始任务，不要把对话变成冗长的设置教程。
• 如果缺少本地技能环境，请先使用 uv 准备环境，再安装依赖或执行任务。除非用户明确要求，否则避免安装到系统 Python。
• 除非用户明确要求指定模型或技术参数，否则由你自行选择模型和默认参数。
• 结果准备好后立即返回。不要让用户追问“图片在哪里？”
• 如果用户询问如何充值、购买点数、添加余额或购买令牌，请使用 references/credits-and-recharge.md 并遵循其中的充值指引流程。
• 如果任务因点数不足而失败，不要只返回原始错误。请使用 references/credits-and-recharge.md 解释失败原因并提供充值指引。
• 如果有可用的更新提醒，请用一句简短、不阻碍任务的提示说明，并继续当前任务。

脚本

scripts/ensure_sdk.py

跨平台（Windows / macOS / Linux）脚本，使用 uv pip install --python <interpreter> 将 fotor-sdk 安装或升级到 PyPI 上的最新版本。每项任务执行前都要运行。

• 无参数 — 安装或升级到 PyPI 上的最新版本
• --upgrade — 执行相同操作，作为显式别名保留

scripts/run_task.py

根据 JSON 执行一个或多个 Fotor 任务。负责初始化客户端、轮询和进度处理。

单个任务：

echo '{"task_type":"text2image","params":{"prompt":"A cat","model_id":"seedream-4-5-251128"}}' \
  | ./.venv/bin/python scripts/run_task.py

批量（数组）：

echo '[
  {"task_type":"text2image","params":{"prompt":"A cat","model_id":"seedream-4-5-251128"},"tag":"cat"},
  {"task_type":"text2video","params":{"prompt":"Sunset","model_id":"kling-v3","duration":5},"tag":"sunset"}
]' | ./.venv/bin/python scripts/run_task.py --concurrency 5

选项： --input FILE、--concurrency N（默认值为 5）、--poll-interval S（默认值为 2.0）、--timeout S（默认值为 1200）。

输出： 包含 task_id、status、success、result_url、error、elapsed_seconds、creditsIncrement、tag 的 JSON。

自动回退：

• 如果任务在主模型上失败，且当前的 task_type + model_id 与内置回退映射匹配，run_task.py 会自动使用回退模型重试一次。
• 如果任务因点数不足而失败（code=510 / No enough credits），run_task.py 会立即返回失败结果，不会使用回退模型重试。
• 输出包含 fallback_used、original_model_id 和 fallback_model_id。

scripts/upload_image.py

通过 Fotor 的签名上传流程上传本地图片文件，并返回可重复使用的图片 URL。

./.venv/bin/python scripts/upload_image.py ./input.jpg --task-type image2image

该脚本：

• 使用映射的上传 type 和 suffix 调用 /v1/upload/sign
• 将本地文件上传到签名目标
• 输出包含 file_url 和 upload_url 的 JSON

对于基于图片的任务，请将 file_url 用作 image_url、start_image_url、end_image_url，或 image_urls 中的一个条目。

受支持的任务到上传类型映射：

• image2image -> img2img
• image_upscale -> img_upscale
• background_remove -> bg_remove
• single_image2video -> img2video
• start_end_frame2video -> img2video
• multiple_image2video -> img2video

scripts/check_skill_update.py

检查当前安装源是否有可用的新版本技能。

./.venv/bin/python scripts/check_skill_update.py --mark-notified --check-interval-hours 24

当安装源元数据不可用时，用于开发／测试：

./.venv/bin/python scripts/check_skill_update.py --install-source skills-github --slug fotor-skills --current-version 1.0.0 --github-source fotor-ai/fotor-skills --mark-notified --check-interval-hours 24

此脚本：

• 首先检测安装源：clawhub 或 skills-github
• 对于 clawhub，读取已安装的 _meta.json，并通过 clawhub inspect <slug> --json 获取最新版本
• 对于 skills-github，读取本地 SKILL.md 前置元数据中的顶层 version 字段，回退到旧版 metadata.version，查找 GitHub 源，并在有可用内容时获取远程 SKILL.md 版本及 CHANGELOG.md 摘要
• 输出包含 install_source、current_version、latest_version、update_available 和 should_notify 的 JSON
• 使用 --mark-notified 时，将上次通知的版本存储在本地状态文件中
• 缓存上次成功的版本检查，并通过 --check-interval-hours 支持设置最短重新检查间隔（默认 24 小时）
• 包含 changelog_preview，便于提醒中提及主要更新，而不必倾倒完整更新日志
• 支持 --install-source、--slug、--current-version 和 --github-source 等开发／测试覆盖参数

参考文件

仅在符合当前需求时阅读相应的参考文件。默认不要加载所有文件。

任务执行参考

在选择模型、验证参数，或将含糊的用户请求映射到推荐工作流时阅读：

• references/image_models.md -- 图像模型 ID、T2I/I2I 能力、各模型的参数限制（分辨率、比例、输入限制、最大参考数）
• references/video_models.md -- 视频模型 ID、T2V/I2V/SE/MI 能力、各模型的参数限制（时长、分辨率、比例、输入限制、音频）
• references/parameter_reference.md -- 所有 8 种任务类型的完整函数签名和参数表
• references/image_scenarios.md -- 图像生成的场景到模型映射（T2I、I2I、工具）；用户意图含糊时阅读
• references/video_scenarios.md -- 视频生成的场景到模型映射（T2V、I2V、SE、MI）；用户意图含糊时阅读

运维参考

仅在用户询问安装、升级、工作区布局、获取 API 密钥或官方 fotor-skills 主页时阅读。执行常规图像／视频任务时不要阅读。

• references/credits-and-recharge.md -- 额度查询、支付链接、充值指引及额度不足的处理方式
• references/get_api_key.md -- 如何提供官方 fotor-skills 主页、引导用户前往 API 密钥控制台入口，以及配置 FOTOR_OPENAPI_KEY
• references/install-or-upgrade.md -- 如何通过 ClawHub 和 npx skills 安装或升级 fotor-skills，以及如何简洁且不强硬地提醒用户升级

工作流

1. 如果缺少 uv，请先使用 Setup 中适用于当前平台的安装程序进行安装。
2. 如果 uv 尚未提供 Python 3.12，请运行 uv python install 3.12。
3. 如果缺少 .venv，请使用 uv venv --python 3.12 .venv 创建它。
4. 每次执行任务前，运行 ./.venv/bin/python scripts/ensure_sdk.py，使用 uv 安装或升级到最新的 fotor-sdk。
5. .venv 准备就绪且 ensure_sdk.py 执行完毕后，静默运行 ./.venv/bin/python scripts/check_skill_update.py --mark-notified --check-interval-hours 24。不要手动检查状态文件。仅当它报告 should_notify: true 时，才读取 references/install-or-upgrade.md 并发送一条简短、非阻塞的更新提醒。如果检查失败或超时，请忽略并继续，不要提及失败。
6. 如果用户在设置期间询问如何获取 API 密钥，或想要官方 fotor-skills 主页，请读取 references/get_api_key.md，并在展开介绍更低层级的设置细节前提供这两个链接。
7. 确认已设置 FOTOR_OPENAPI_KEY。
8. 如果用户询问账户额度、充值、购买额度或支付链接，请读取 references/credits-and-recharge.md，然后使用其中适当的余额或支付链接流程。
9. 对于从本地文件开始的图像任务，先运行 ./.venv/bin/python scripts/upload_image.py <local-file> --task-type <task-type>，并保留返回的 file_url。
10. 阅读相应的模型参考文档以选择 model_id。每个模型的规格部分都会列出支持的分辨率、宽高比、时长、输入限制和最大参考图像数。
11. 如果用户意图不明确（未指定具体模型），请查阅场景文件（image_scenarios.md / video_scenarios.md）以选择推荐的模型和参数。
12. 验证参数是否符合所选模型的规格后再调用——检查分辨率、宽高比、时长和多图限制。
13. 快速路径——将 JSON 传入 ./.venv/bin/python scripts/run_task.py（单项和批量任务均适用）。
14. 自定义路径——直接使用 SDK 编写内联 Python 代码（参见下方示例），仍优先使用本地 .venv 解释器。
15. 检查输出中的 result_url。如果需要更高分辨率，请串接 image_upscale。

如果用户要求查看账户额度或剩余额度，请读取 references/credits-and-recharge.md，并使用其中描述的 SDK 客户端流程，而不是 run_task.py。

内置的自动回退映射定义在 references/fallback_models.json 中。

run_task.py 会直接读取该文件。请将精确的回退配对保留在该文件中，不要在 SKILL.md 或场景参考文档中重复定义。

可用任务类型

task_type	函数	必需参数
text2image	text2image()	prompt、model_id
image2image	image2image()	prompt、model_id、image_urls
image_upscale	image_upscale()	image_url
background_remove	background_remove()	image_url
text2video	text2video()	prompt、model_id
single_image2video	single_image2video()	prompt、model_id、image_url
start_end_frame2video	start_end_frame2video()	prompt、model_id、start_image_url、end_image_url
multiple_image2video	multiple_image2video()	prompt、model_id、image_urls（≥2）

完整参数详情（默认值、on_poll、**extra），请阅读 references/parameter_reference.md。

额度与充值

对于任何余额查询、充值指引或额度不足的情况，请阅读 references/credits-and-recharge.md。

让 SKILL.md 专注于路由：

• 用户询问剩余余额、总额度、充值、补充额度或支付链接时，请使用额度参考文档。
• 任务因 code=510 或 No enough credits 失败时，也请使用同一份参考文档。
• 将详细的 API 示例、字段含义和面向用户的充值说明保留在参考文档中，不要扩展到此主技能文件里。

内联 Python 示例

当 scripts/run_task.py 无法满足需求时（自定义逻辑、串联任务、进度回调）：

客户端初始化

import os
from fotor_sdk import FotorClient
client = FotorClient(api_key=os.environ["FOTOR_OPENAPI_KEY"])

单个任务

from fotor_sdk import text2image
result = await text2image(client, prompt="A diamond kitten", model_id="seedream-4-5-251128")
print(result.result_url)

使用 TaskRunner 批量执行

from fotor_sdk import TaskRunner, TaskSpec
runner = TaskRunner(client, max_concurrent=5)
specs = [
    TaskSpec("text2image", {"prompt": "A cat", "model_id": "seedream-4-5-251128"}, tag="cat"),
    TaskSpec("text2video", {"prompt": "Sunset", "model_id": "kling-v3", "duration": 5}, tag="sunset"),
]
results = await runner.run(specs)

带音频的视频

from fotor_sdk import text2video
result = await text2video(client, prompt="Jazz band", model_id="kling-v3",
                          audio_enable=True, audio_prompt="Smooth jazz")

TaskResult

result.success          # bool: True when COMPLETED with result_url
result.result_url       # str | None
result.status           # TaskStatus: COMPLETED / FAILED / TIMEOUT / IN_PROGRESS / CANCELLED
result.error            # str | None (e.g. "NSFW_CONTENT")
result.elapsed_seconds  # float
result.creditsIncrement # int | float: credits consumed by this task
result.metadata         # dict (includes "tag" from TaskRunner)

错误处理

• 单个任务：捕获 FotorAPIError（具有 .code 属性）。
• 批量任务：逐项检查 result.success；Runner 不会因单项失败而抛出异常。
• NSFW：在 TaskResult 中显示为 error="NSFW_CONTENT"。
• 额度不足：如果 result.error、异常文本或组合后的回退错误包含 code=510 或 No enough credits，则将其视为需要充值的情况。告知用户额度不足，然后获取并提供支付链接。

如需排查问题，请启用 SDK 调试日志：logging.getLogger("fotor_sdk").setLevel(logging.DEBUG)。