linkfox-multimodal-recognize-image

画像認識

このスキルでは、マルチモーダル画像認識 API を使用して URL の画像を分析し、ユーザーの意図に基づいて有用な情報を抽出する方法を説明します。

基本概念

画像認識ツールは、画像 URL と、画像について知りたい内容を記述した任意の自然言語の要件を受け取ります。バックエンドではマルチモーダル AI モデルを使用して視覚的な内容を解釈し、テキスト形式の説明または分析結果を返します。

対応形式：JPG、JPEG、PNG、GIF、WebP、BMP。

仕組み：一般公開されている画像 URL と要件（画像から何を知りたいか）を指定します。サービスは画像をダウンロードし、マルチモーダル分析を実行して、テキスト形式の結果を返します。

パラメーターガイド

パラメーター	必須	説明
imageUrl	はい	画像を指す、一般公開されている URL です。JPG、JPEG、PNG、GIF、WebP、または BMP である必要があります。最大 1000 文字です。
requirement	いいえ	画像から特定または分析したい内容を記述する自然言語の説明です。省略した場合は「この画像の内容を説明してください」がデフォルトになります。最大 1000 文字です。

requirement パラメーターを記述する際のヒント

1. 具体的にする：「この画像を分析して」ではなく、「棚に見えるすべての商品を列挙し、カテゴリを推定してください」と指定します。
2. 目的を明記する：テキストを抽出する場合は、「画像内に見えるすべてのテキストを抽出してください」と指定します。オブジェクトを特定する場合は、「主なオブジェクトとその色を特定してください」と指定します。
3. 必要に応じて文脈を提供する：商品画像の場合は、「これは EC サイトの商品掲載画像です」と伝えると、モデルが分析内容を調整できます。

ローカル画像のアップロード

このツールには、一般公開されている画像 URL が必要です。ユーザーがローカル画像ファイルのパス（例：C:\Users\...\photo.png、/home/.../image.jpg）を指定した場合は、まずアップロードして公開 URL を取得する必要があります。

アップロードスクリプトを実行します：

python scripts/upload_image.py /path/to/local/image.png

スクリプトは公開 URL（有効期間は 24 時間）を返します。この URL を画像 URL パラメーターとして使用できます。

使用例

1. 画像の一般的な説明

• ユーザーの依頼：「この写真には何が写っていますか？」
• imageUrl に指定された URL を設定し、requirement はデフォルトのままにします。

2. 商品画像の分析

• ユーザーの依頼：「この Amazon の商品画像を分析し、表示されている主なセールスポイントを列挙してください。」
• requirement に次のように設定します：「これは Amazon の商品掲載画像です。画像に表示されている商品、主な特徴、セールスポイントを特定してください。」

3. 画像からのテキスト抽出

• ユーザーの依頼：「このスクリーンショットのテキストを読んでください。」
• requirement に次のように設定します：「この画像に見えるすべてのテキストを、可能な限りレイアウトを維持して抽出してください。」

4. A+ ページ画像のレビュー

• ユーザーの依頼：「この A+ コンテンツ画像が何を伝えているか説明してください。」
• requirement に次のように設定します：「これは Amazon A+ 商品説明画像です。視覚的な内容、主なメッセージ、ブランディング要素を説明してください。」

5. 比較／詳細の確認

• ユーザーの依頼：「商品とそのパッケージの違いは何ですか？」
• requirement に次のように設定します：「画像に表示されている商品とパッケージの違いを特定し、説明してください。」

呼び出し方法

• API エンドポイント：POST /multimodal/recognizeImage（パラメーター、レスポンス、エラーコードの詳細は references/api.md を参照）
• Python スクリプト：python scripts/multimodal_recognize_image.py '<JSON 参数>' [--inline]
• コスト制限：このツールは計算リソースを消費します。同一セッションでは同じパラメーターの組み合わせでデフォルトで 1 回だけ呼び出され、スクリプトには 24 時間のローカルキャッシュがあります。失敗または空の結果が返された場合、キーワードを自動的に変更したり、ページをめくったり、郵便番号を変えたりして連続して試行してはいけません。検索を続ける必要がある場合は、追加のコストが発生することを先にユーザーに伝えてください。

出力ポリシー（スクリプトのデフォルト動作）：

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-multimodal-recognize-image-<timestamp>.json に書き込みます（<cwd> はスクリプト実行時の作業ディレクトリです。Claude Code では現在のプロジェクトディレクトリです。<session> は環境変数 SESSION_ID から取得され、ユーザーのタスクごとに自動的にまとめられます。/tmp への書き込みは禁止です。現在のディレクトリに書き込めない場合はエラーになります）。
• レスポンス本文が 8 KB 以下の場合：ファイルに保存した後、完全な JSON を stdout に出力します。
• レスポンス本文が 8 KB を超える場合：ファイルに保存した後、stdout には要約のみを出力します（トップレベルのフィールド、total／costToken などの一般的なカウント、最大のリストフィールドの長さと先頭 3 件のサンプル）。
• --inline を付けると、stdout に全内容を強制的に出力します（同様にファイルにも保存します）。

データの読み取りに関する推奨事項：まず要約を確認し、十分かどうか判断してください。具体的なフィールドが必要な場合は、JSON 全体をコンテキストに読み込むのを避けるため、保存された json ファイルから必要に応じて jq または ConvertFrom-Json を使って抽出してください。

認証と計算リソースの問題の解決

次の異常が発生した場合は、references/onboarding.md の案内に従って問題を解決してください：

例外的な状況

• API Key が未設定：環境変数 LINKFOX_AGENT_API_KEY も LINKFOXAGENT_API_KEY も設定されていません。
• 401 または402のステータスコードが返された場合
• 計算リソースまたは残高が不足している旨の応答：メッセージに「計算リソースの残高不足／請求額不足／残高不足／quota exceeded／insufficient balance／プランの有効期限切れ／チャージが必要／チャージしてください」、または同様の意味の内容が含まれている場合。

表示ルール

1. 分析結果を明確に表示する：返されたテキスト分析を読みやすい形式で提示します。内容に応じて箇条書きまたは段落を使用します。
2. 情報を捏造しない：API が実際に返した情報のみを伝えます。応答に含まれていない視覚的な詳細を追加しないでください。
3. 形式のサポート：画像 URL が無効な場合、または形式がサポートされていない場合は、その制限について説明し、サポートされている形式（JPG、JPEG、PNG、GIF、WebP、BMP）を列挙します。
4. エラー処理：API がエラーステータスを返した場合は、応答に基づいて問題を説明し、修正方法（例：URL が一般公開されていることの確認、画像形式の確認）を提案します。
5. トークン使用量：ユーザーからコストについて尋ねられた場合は、応答に含まれる costToken の値に言及してもかまいません。

ユーザーの表現とシナリオのクイックリファレンス

該当する -- 画像分析タスク：

ユーザーの発言	シナリオ
"この画像／写真には何が写っていますか？"	一般的な画像の説明
"この商品の画像を分析してください"	商品の視覚的分析
"この画像内のテキストを読んでください"	OCR／テキスト抽出
"A+ページの画像を説明してください"	Eコマースコンテンツの確認
"このスクリーンショットには何が表示されていますか？"	スクリーンショットの解釈
"この写真に写っている物体を特定してください"	物体検出／一覧表示

該当しない -- 画像認識を超える機能が必要なタスク： ``

• 画像の生成または編集
• 動画分析
• ローカルファイルパスからの画像分析（URL のみサポートされています）
• 画像検索または逆画像検索

計算リソースの消費ルール

動的ルールに基づいて課金されます：消費する計算リソース = 入力にかかる計算リソース + 出力結果にかかる計算リソース。

重要：このスキルのサービスは倍率に基づいて動的に計算されるため、一度に大量の計算リソースを消費する可能性があります。必ずユーザーに注意を促し、続行するかどうかはユーザーに判断してもらってください。

フィードバック：

次のいずれかに該当する場合は、Feedback API を通じてフィードバックを自動検出して報告します。

1. このスキルで説明されている機能または目的が、実際の動作と一致しない
2. このスキルの結果がユーザーの意図と一致しない
3. ユーザーがこのスキルへの不満または称賛を表明する
4. 改善できると思われることがある

references/api.md に記載されている方法でフィードバック API を呼び出してください。ユーザーの作業を中断しないでください。

---

高品質でプロフェッショナルな越境Eコマース向けスキルをさらに利用するには、LinkFox Skills を設定してください。