fotor-skills

fotor-skills

AI 画像生成、AI 写真編集、AI 動画生成、商品写真、広告クリエイティブ、SNS グラフィック、背景削除、写真の修復、画像のアップスケールに対応する Fotor OpenAPI スキルです。

このスキルは、SDK の用語ではなく、まずユーザーが求める成果に基づいてリクエストを照合します。実行に必要な場合を除き、技術的な詳細は表に出さないでください。

このスキルが適合するケース

次のような成果をユーザーが求めている場合に、このスキルを使用します。

• テキストプロンプトから AI 画像を生成する
• 既存の写真を編集したり、スタイルを変更したりする
• 商品写真を、EC サイトや広告ですぐに使える素材に仕上げる
• ポスター、バナー、カバー、サムネイル、SNS グラフィックを作成する
• 画像の背景を削除または差し替える
• ぼやけた写真や古い写真を修復、補正、またはアップスケールする
• テキスト、1 枚の画像、複数の画像、または開始フレームと終了フレームから AI 動画を生成する
• ブランディング、コンテンツ、マーケティングキャンペーン向けのビジュアル素材を一括で制作する

検索意図のカバー範囲

このスキルで照合できるようにする代表的な検索フレーズは次のとおりです。

• AI 写真エディター
• AI 画像ジェネレーター
• AI 動画ジェネレーター
• 画像から画像
• テキストから画像
• テキストから動画
• 商品写真ジェネレーター
• 広告クリエイティブジェネレーター
• マーケティングビジュアルジェネレーター
• ポスターメーカー
• バナーメーカー
• SNS 投稿ジェネレーター
• カバー・サムネイルジェネレーター
• 背景削除ツール
• 背景の差し替え
• 写真の修復
• 画像アップスケーラー
• EC 画像生成
• ブランド素材の生成

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、パラメータ表から説明を始めないでください。
• 不足している情報の確認は、一度に1つだけにしてください。
• 必要最小限の情報がそろったら、ただちに実行してください。実際に実行を開始し、その後に結果または明確な進行状況を伝えるのでない限り、「これから開始します」のような曖昧なつなぎのメッセージは送らないでください。
• 実行にある程度の時間がかかる場合は、タスクを実行中であることを伝え、「通常、数秒から数十秒ほどかかります。完了したら結果をお送りします」のように短い目安を示してください。
• 認証情報が不足している場合は、その問題を速やかに解決してから、長いセットアップの説明に切り替えることなく、元のタスクに戻ってください。
• ローカルのスキル環境がない場合は、依存関係をインストールしたりタスクを実行したりする前に、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 から1つ以上の 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 はフォールバックモデルで自動的に1回再試行します。
• クレジット不足（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. Python 3.12 が uv で利用できない場合は、uv python install 3.12 を実行します。
3. .venv がない場合は、uv venv --python 3.12 .venv で作成します。
4. 各タスクの前に、./.venv/bin/python scripts/ensure_sdk.py を実行し、最新の fotor-sdk を uv でインストールまたはアップグレードします。
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 を読み、簡潔で作業を妨げない更新リマインダーを1件送信します。チェックに失敗するかタイムアウトした場合は、失敗について触れずに無視して続行します。
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 を読み、run_task.py ではなく、そこに記載されている SDK クライアントのフローを使用します。

組み込みの自動フォールバックマッピングは 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)

エラー処理

• 単一タスク：.code 属性を持つ FotorAPIError をキャッチします。
• バッチ処理：項目ごとに result.success を確認します。runner は個別の失敗では例外を発生させません。
• NSFW：TaskResult では error="NSFW_CONTENT" として表示されます。
• クレジット不足：result.error、例外テキスト、または統合されたフォールバックエラーに code=510 または No enough credits が含まれている場合は、チャージが必要なケースとして扱います。クレジットが不足していることをユーザーに伝えた後、支払いリンクを取得して提示します。

トラブルシューティングでは、SDK のデバッグログを有効にします：logging.getLogger("fotor_sdk").setLevel(logging.DEBUG)。