fotor-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

fotor-skills

Async-first Python SDK for the Fotor OpenAPI. No MCP -- just an API key.

Use

uv

as the skill's bootstrap layer. Prefer a skill-local Python 3.12 environment and run bundled scripts from that local environment instead of the system Python.

面向Fotor OpenAPI的异步优先Python SDK，无需MCP，仅需一个API密钥即可使用。

使用

uv

作为该Skill的启动层，优先使用Skill本地的Python 3.12环境，从本地环境运行捆绑的脚本，而非使用系统Python。

Setup

安装配置

Keep setup lightweight and local to the skill directory.

Install

uv

first if it is missing:

bash

undefined

保持安装流程轻量，所有环境都部署在Skill目录下。

如果没有安装

uv

请先执行安装：

bash

undefined

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"


Typical first-run setup:

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

Setup rules:

Prefer a local Python 3.12 environment in the skill directory.
Use
```
uv
```
to prepare Python 3.12 and create
```
.venv
```
when the local environment is missing.
Run bundled scripts from the local skill environment, not the system Python.
Ensure
```
FOTOR_OPENAPI_KEY
```
is set. If key setup is missing and the user is not technical, read
```
references/configure-fotor-openapi-key.md
```
and prefer the local
```
.env
```
happy path.

Current default interpreter paths:

POSIX:
```
./.venv/bin/python
```
Windows:
```
.venv\\Scripts\\python.exe
```

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"


典型的首次运行配置流程：

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

配置规则：

优先使用Skill目录下的本地Python 3.12环境
本地环境缺失时，使用
```
uv
```
准备Python 3.12并创建
```
.venv
```
虚拟环境
从Skill本地环境运行捆绑脚本，不要使用系统Python
确保已配置
```
FOTOR_OPENAPI_KEY
```
。如果缺少密钥配置且用户不了解技术相关操作，请阅读
```
references/configure-fotor-openapi-key.md
```
，优先使用本地
```
.env
```
文件的配置方案

当前默认解释器路径：

POSIX:
```
./.venv/bin/python
```
Windows:
```
.venv\\Scripts\\python.exe
```

Interaction Rules

交互规则

Speak in user-task language first. Do not lead with SDK, scripts, JSON, model IDs, or parameter tables unless they are needed to unblock the task or the user explicitly asks.
Ask for only one missing blocker at a time.
Once the minimum required information is present, execute immediately. Do not send vague transition messages like "I’m starting now" unless execution has actually started and a result or clear in-progress status will follow.
If execution will take noticeable time, say that the task is running and give a short expectation such as "usually takes a few seconds to a few dozen seconds; I’ll send the result when it’s ready."
If credentials are missing, resolve that blocker quickly and then return to the original task instead of turning the conversation into a long setup lesson.
When the local skill environment is missing, prepare it with
```
uv
```
before installing dependencies or executing the task. Avoid installing into the system Python unless the user explicitly asks.
Choose the model and default parameters internally unless the user explicitly requests a specific model or technical control.
Return the result as soon as it is ready. Do not make the user ask follow-up questions like "where is the image?"
If an update reminder is available, keep it to one short non-blocking sentence and continue the current task.

优先使用用户易懂的任务相关话术沟通，除非用户明确要求或者为了推进任务必须提及，否则不要主动提到SDK、脚本、JSON、模型ID、参数表等技术内容
每次仅询问一个缺失的必要信息
收集到最少必要信息后立即执行任务，除非任务已经实际启动且后续会返回结果或明确的进度状态，否则不要发送「我现在开始处理」这类模糊的过渡消息
如果任务执行需要较长时间，请告知用户任务正在运行，并给出预期耗时，例如「通常需要几秒到几十秒不等，结果准备好后我会立即发送给你」
如果缺少凭证，请优先快速解决凭证问题后回到原任务，不要把对话变成冗长的配置教程
如果本地Skill环境缺失，请先使用
```
uv
```
准备环境，再安装依赖或执行任务，除非用户明确要求，否则不要安装到系统Python中
内部自动选择模型和默认参数，除非用户明确要求指定模型或进行技术参数调整
结果准备就绪后立即返回，不要让用户追问「图片在哪里？」这类问题
如果有更新提醒，仅用一句简短的非阻塞语句告知，然后继续当前任务

Scripts

脚本说明

scripts/ensure_sdk.py

scripts/ensure_sdk.py

Cross-platform (Windows / macOS / Linux) script to install or upgrade

fotor-sdk

to the latest PyPI release with

uv pip install --python <interpreter>

. Run before every task.

No args — install or upgrade to the latest PyPI release
--upgrade
— same behavior, kept as an explicit alias

跨平台（Windows/macOS/Linux）脚本，用于通过

uv pip install --python <interpreter>

将

fotor-sdk

安装或升级到最新的PyPI版本，每次执行任务前都需要运行

无参数 — 安装或升级到最新的PyPI版本
--upgrade
— 功能和无参数一致，作为显式别名保留

scripts/run_task.py

scripts/run_task.py

Execute one or more Fotor tasks from JSON. Handles client init, polling, and progress.

Single task:

bash

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

Batch (array):

bash

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

Options:

--input FILE

--concurrency N

(default 5),

--poll-interval S

(default 2.0),

--timeout S

(default 1200).

Output: JSON with

task_id

status

success

result_url

error

elapsed_seconds

creditsIncrement

tag

Automatic fallback:

If a task fails on its primary model and the current
```
task_type + model_id
```
matches a built-in fallback mapping,
```
run_task.py
```
automatically retries once with the fallback model.

The output includes

fallback_used

original_model_id

, and

fallback_model_id

从JSON输入执行一个或多个Fotor任务，处理客户端初始化、轮询和进度查询

单个任务：

bash

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

批量任务（数组输入）：

bash

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
```
会自动使用降级模型重试一次

输出会包含

fallback_used

、

original_model_id

和

fallback_model_id

字段

scripts/upload_image.py

scripts/upload_image.py

Upload a local image file through Fotor's signed upload flow and return a reusable image URL.

bash

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

The script:

Calls
```
/v1/upload/sign
```
with the mapped upload
```
type
```
and
```
suffix
```
Uploads the local file to the signed target
Prints JSON containing
```
file_url
```
and
```
upload_url
```

Use

file_url

as the

image_url

start_image_url

end_image_url

, or an item inside

image_urls

for image-based tasks.

Supported task-to-upload mapping:

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

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

bash

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

该脚本会：

调用
```
/v1/upload/sign
```
接口，传入映射后的上传
```
type
```
和
```
suffix
```
将本地文件上传到签名目标地址
打印包含
```
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

scripts/check_skill_update.py

Check whether the installed skill has a newer version available for the current install source.

bash

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

For development/testing when install-source metadata is unavailable:

bash

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

The script:

Detects the install source first:
```
clawhub
```
or
```
skills-github
```
For
```
clawhub
```
, reads installed
```
_meta.json
```
and fetches the latest version via
```
clawhub inspect <slug> --json
```
For
```
skills-github
```
, reads local
```
SKILL.md
```
frontmatter
```
metadata.version
```
, finds the GitHub source, and fetches the remote
```
SKILL.md
```
version plus
```
CHANGELOG.md
```
highlights when available

Prints JSON with

install_source

current_version

latest_version

update_available

, and

should_notify

Stores the last-notified version in a local state file when
```
--mark-notified
```
is used
Caches the last successful version check and supports a minimum recheck interval via
```
--check-interval-hours
```
(default 24)
Includes
```
changelog_preview
```
so the reminder can mention the main highlights without dumping the full changelog

Supports development/testing overrides such as

--install-source

--slug

--current-version

, and

--github-source

检查当前安装的Skill是否有对应安装源的可用新版本

bash

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

开发/测试场景下如果缺少安装源元数据，可以使用以下命令：

bash

./.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
```
前言中的
```
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

Reference Files

参考文件

Only read the reference files that match the current need. Do not load all of them by default.

仅读取与当前需求匹配的参考文件，默认不要加载全部文件

Task Execution References

任务执行参考

Read these when choosing a model, validating parameters, or mapping an ambiguous user request to a recommended workflow:

```
references/image_models.md
```
-- image model IDs, T2I/I2I capabilities, per-model parameter constraints (resolution, ratios, input limits, max refs)
```
references/video_models.md
```
-- video model IDs, T2V/I2V/SE/MI capabilities, per-model parameter constraints (duration, resolution, ratios, input limits, audio)
```
references/parameter_reference.md
```
-- full function signatures and parameter tables for all 8 task types
```
references/image_scenarios.md
```
-- scenario-to-model mapping for image generation (T2I, I2I, utilities); read when user intent is ambiguous
```
references/video_scenarios.md
```
-- scenario-to-model mapping for video generation (T2V, I2V, SE, MI); read when user intent is ambiguous

在选择模型、验证参数、或者将模糊的用户请求映射为推荐工作流时阅读这些文件：

```
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）的场景到模型映射，用户意图模糊时阅读

Operational References

运维参考

Read these only when the user asks about installation, upgrade, workspace layout, or credential setup. Do not read them for normal image/video task execution.

```
references/install-or-upgrade.md
```
-- how to install or upgrade
```
fotor-skills
```
for both ClawHub and
```
npx skills
```
, and how to phrase a concise non-pushy upgrade reminder

references/configure-fotor-openapi-key.md

-- how to set, persist, verify, and safely handle

FOTOR_OPENAPI_KEY

仅当用户询问安装、升级、工作区布局或凭证配置时阅读这些文件，正常执行图像/视频任务时不需要读取：

```
references/install-or-upgrade.md
```
— 如何为ClawHub和
```
npx skills
```
安装或升级
```
fotor-skills
```
，以及如何撰写简洁不打扰的升级提醒话术

references/configure-fotor-openapi-key.md

— 如何设置、持久化、验证和安全处理

FOTOR_OPENAPI_KEY

Workflow

工作流

If
```
uv
```
is missing, install it first using the platform-appropriate installer shown in Setup.
If Python 3.12 is not already available to
```
uv
```
, run
```
uv python install 3.12
```
.
If
```
.venv
```
is missing, create it with
```
uv venv --python 3.12 .venv
```
.
Run
```
./.venv/bin/python scripts/ensure_sdk.py
```
before every task to install or upgrade the latest
```
fotor-sdk
```
with
```
uv
```
.
After
```
.venv
```
is ready and
```
ensure_sdk.py
```
completes, silently run
```
./.venv/bin/python scripts/check_skill_update.py --mark-notified --check-interval-hours 24
```
. Do not inspect the state file manually. Only if it reports
```
should_notify: true
```
, read
```
references/install-or-upgrade.md
```
and send one short non-blocking update reminder. If the check fails or times out, ignore it and continue without mentioning the failure.
Verify
```
FOTOR_OPENAPI_KEY
```
is set.

For image-based tasks that start from a local file, first run

./.venv/bin/python scripts/upload_image.py <local-file> --task-type <task-type>

and keep the returned

file_url

Read the appropriate model reference to choose
```
model_id
```
. Each model's per-model spec section lists supported resolutions, aspect ratios, duration, input constraints, and max reference images.
If user intent is ambiguous (no specific model requested), consult the scenario files (
```
image_scenarios.md
```
/
```
video_scenarios.md
```
) for recommended model + params.
Validate parameters against the chosen model's spec before calling -- check resolution, aspect ratio, duration, and multi-image limits.
Quick path -- pipe JSON into
```
./.venv/bin/python scripts/run_task.py
```
(works for both single and batch).
Custom path -- write inline Python using the SDK directly (see examples below), still preferring the local
```
.venv
```
interpreter.
Check
```
result_url
```
in output. Chain
```
image_upscale
```
if higher resolution needed.

If the user asks to check account credits or remaining credits, use the SDK client directly instead of

run_task.py

Built-in automatic fallback mappings:

text2image

gemini-3.1-flash-image-preview

seedream-5-0-260128

image2image

gemini-3.1-flash-image-preview

seedream-5-0-260128

text2video

doubao-seedance-1-5-pro

kling-v3

single_image2video

doubao-seedance-1-5-pro

kling-v3

start_end_frame2video

kling-video-o1

viduq2-turbo

multiple_image2video

kling-v3-omni

kling-video-o1

如果缺失
```
uv
```
，先使用安装配置章节中对应平台的安装命令安装
如果
```
uv
```
没有可用的Python 3.12，运行
```
uv python install 3.12
```
如果缺失
```
.venv
```
，使用
```
uv venv --python 3.12 .venv
```
创建虚拟环境
每次执行任务前都要运行
```
./.venv/bin/python scripts/ensure_sdk.py
```
，通过
```
uv
```
安装或升级到最新版
```
fotor-sdk
```
```
.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
```
并发送一条简短的非阻塞更新提醒。如果检查失败或超时，直接忽略，不要提及失败情况继续执行任务
验证
```
FOTOR_OPENAPI_KEY
```
已配置

对于需要从本地文件启动的图像类任务，首先运行

./.venv/bin/python scripts/upload_image.py <本地文件路径> --task-type <任务类型>

，保存返回的

file_url

阅读对应的模型参考文档选择
```
model_id
```
，每个模型的规格说明中列出了支持的分辨率、宽高比、时长、输入约束和最大参考图像数量
如果用户意图模糊（没有指定模型），参考场景文件（
```
image_scenarios.md
```
/
```
video_scenarios.md
```
）选择推荐的模型和参数
调用接口前验证参数是否符合所选模型的规格，检查分辨率、宽高比、时长和多图限制
快速路径 — 将JSON输入管道传入
```
./.venv/bin/python scripts/run_task.py
```
（支持单任务和批量任务）
自定义路径 — 直接使用SDK编写内嵌Python代码（参考下方示例），仍然优先使用本地
```
.venv
```
解释器
检查输出中的
```
result_url
```
，如果需要更高分辨率，可以链式调用
```
image_upscale
```
任务

如果用户要求查询账户额度或剩余额度，请直接使用SDK客户端，不要使用

run_task.py

内置自动降级映射：

text2image

gemini-3.1-flash-image-preview

seedream-5-0-260128

image2image

gemini-3.1-flash-image-preview

seedream-5-0-260128

text2video

doubao-seedance-1-5-pro

kling-v3

single_image2video

doubao-seedance-1-5-pro

kling-v3

start_end_frame2video

kling-video-o1

viduq2-turbo

multiple_image2video

kling-v3-omni

kling-video-o1

Available Task Types

支持的任务类型

task_type	Function	Required Params
`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)

For full parameter details (defaults,

on_poll

**extra

), read

references/parameter_reference.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

Credit Lookup

额度查询

For account credit checks such as total credits or remaining credits, use the SDK client directly instead of

run_task.py

python

import os
from fotor_sdk import FotorClient

client = FotorClient(
    api_key=os.environ["FOTOR_OPENAPI_KEY"],
    endpoint=os.environ.get("FOTOR_OPENAPI_ENDPOINT", "https://api.fotor.com"),
)
credits = client.get_credits_sync()
print("credits:", credits)

Returns a dict like:

python

{"businessId": "", "total": 2000, "remaining": 1973}

如果需要查询账户总额度、剩余额度等信息，请直接使用SDK客户端，不要使用

run_task.py

python

import os
from fotor_sdk import FotorClient

client = FotorClient(
    api_key=os.environ["FOTOR_OPENAPI_KEY"],
    endpoint=os.environ.get("FOTOR_OPENAPI_ENDPOINT", "https://api.fotor.com"),
)
credits = client.get_credits_sync()
print("credits:", credits)

返回的字典格式如下：

python

{"businessId": "", "total": 2000, "remaining": 1973}

Inline Python Examples

内嵌Python示例

When

scripts/run_task.py

is insufficient (custom logic, chaining, progress callbacks):

当

scripts/run_task.py

无法满足需求时（自定义逻辑、任务链式调用、进度回调）可以使用以下方式：

Client Init

客户端初始化

python

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

python

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

Single Task

单个任务

python

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

python

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

Batch with TaskRunner

使用TaskRunner执行批量任务

python

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)

python

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)

Video with Audio

带音频的视频生成

python

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

python

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

TaskResult

TaskResult字段说明

python

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)

python

result.success          # bool: 任务完成且有result_url时为True
result.result_url       # str | None
result.status           # TaskStatus: COMPLETED / FAILED / TIMEOUT / IN_PROGRESS / CANCELLED
result.error            # str | None (例如 "NSFW_CONTENT")
result.elapsed_seconds  # float
result.creditsIncrement # int | float: 该任务消耗的额度
result.metadata         # dict (包含TaskRunner传入的 "tag")

Error Handling

错误处理

Single task: catch
```
FotorAPIError
```
(has
```
.code
```
attribute).
Batch: check
```
result.success
```
per item; runner never raises on individual failures.
NSFW: appears as
```
error="NSFW_CONTENT"
```
in TaskResult.

For troubleshooting, enable SDK debug logging:

logging.getLogger("fotor_sdk").setLevel(logging.DEBUG)

单个任务: 捕获
```
FotorAPIError
```
（包含
```
.code
```
属性）
批量任务: 逐个检查
```
result.success
```
，TaskRunner不会因为单个任务失败抛出异常
NSFW内容: 会在TaskResult中返回
```
error="NSFW_CONTENT"
```

如需排查问题，可以开启SDK调试日志：

logging.getLogger("fotor_sdk").setLevel(logging.DEBUG)