octen-image-search

Octen Image Search

テキストクエリまたは参照画像を使ってウェブ上の画像を検索します（API ではリクエストごとに入力を1つだけ受け付けます）。各結果には、サムネイル、ソースページ、寸法、説明が含まれます。

ベータ版です。ベータ版へのアクセスをご希望の場合はお問い合わせください。 Octen Image Search は招待制のベータ版です。https://octen.ai または [email protected] からアクセスをリクエストしてください。 アクセス権がない場合、呼び出しは失敗します。その場合は、ベータ版であることと Octen への問い合わせ方法をユーザーに伝えてください。

UI デザインの参考資料には使用しないでください。 参考用スクリーンショット、構造化されたスタイルトークン、フロントエンドの構築やスタイル変更に使う HTML/CSS スニペットが必要な場合は、octen-design スキルを使用してください（同じエンドポイントに topic=design を指定して検索します）。このスキルは一般的な画像検索用です。

API キーの設定

検索の前に、OCTEN_API_KEY が設定されていることを確認してください。401 が返された場合は検索を中止し、キーが必要であることをユーザーに伝えてください（https://octen.ai）。`403` が返された場合、キーは有効ですがリクエストが拒否されています。ベータ版へのアクセス権がないか、アカウント残高が不足している可能性があるため、両方の可能性とベータ版へのアクセスをリクエストする方法を伝えてください。

他の Octen スキルと同様、該当するエージェントにキーを設定します。

• Claude Code — ~/.claude/settings.json に { "env": { "OCTEN_API_KEY": "your-key" } } を追加します
• Cursor / 汎用シェル — ~/.zshrc または ~/.bashrc に export OCTEN_API_KEY="your-key" を設定します
• Codex — ~/.codex/config.toml の [shell_environment_policy] に set = { OCTEN_API_KEY = "your-key" } を設定します
• OpenClaw — ~/.openclaw/.env に OCTEN_API_KEY=your-key を追加します

エンドポイント

POST https://api.octen.ai/image-search

認証：X-Api-Key: <API_KEY> ヘッダー · Content-Type：application/json

クイックスタート（cURL）

テキストで検索

curl -s -X POST "https://api.octen.ai/image-search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "inputs": [{"type": "text", "data": "red sports car"}],
    "count": 5
  }'

参照画像で検索（URL または Base64）

curl -s -X POST "https://api.octen.ai/image-search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "inputs": [{"type": "image", "url": "https://example.com/car.jpg"}],
    "count": 5
  }'

inputs にはリクエストごとに1つだけ入力できます。テキストクエリ1つ、または画像1つです。両方を指定することはできません（2つ目の入力は 400 で拒否されます）。ローカル画像の場合は、{"type": "image", "data": "<base64>"} を送信してください（Base64 エンコード後で 5MB 以下。JPEG/PNG など）。

パラメーター

パラメーター	型	必須	デフォルト	説明
inputs	array	はい	-	入力は1つだけです：{"type":"text","data":"<query≤500>"}、{"type":"image","url":"<url>"}、または {"type":"image","data":"<base64>"}
topic	string	いいえ	general	general（ウェブ画像）または design（UI デザインのコーパス。octen-design スキルを推奨）
count	integer	いいえ	5	結果の件数（1～10）
include_domains	string[]	いいえ	-	指定したドメインの画像のみを含めます
exclude_domains	string[]	いいえ	-	指定したドメインの画像を除外します
safesearch	string	いいえ	strict	アダルトコンテンツフィルター：off または strict
html_snippet	object	いいえ	{"enable": false}	{enable, max_tokens (デフォルト5000、100～100000)} — デザイン向けの HTML/CSS スニペット（主に topic=design と併用すると便利です）

このエンドポイントには時間フィルターがありません。time_range、start_time、end_time はここでは黙って無視され、フィルターなしの結果が 200 で返されます（エラーにはなりません）。そのため、期間を指定した画像検索は、失敗しても気づきにくい場合があります。これらのパラメーターに対応している octen-search と octen-video-search で使用してください。

レスポンス形式

フィールド	型	説明
request_id	string	一意のリクエスト識別子
data.results[]	array	画像結果の一覧
data.results[].title	string	画像／ページのタイトル
data.results[].url	string	フル解像度の画像 URL
data.results[].thumbnail	string?	サムネイル URL
data.results[].source_page	string?	画像が見つかったページ
data.results[].description	string?	説明／代替テキスト
data.results[].width	integer?	画像の幅（px）
data.results[].height	integer?	画像の高さ（px）
data.results[].summary	string?	構造化されたスタイルの概要（主に topic=design）
data.results[].html_snippet	string?	HTML/CSS スニペット（主に topic=design）
data.results[].time_published	string?	公開時刻、ISO 8601
data.results[].time_last_crawled	string?	最終クロール時刻、ISO 8601
meta.latency	number	レスポンス時間（ミリ秒）
meta.warning	string?	警告メッセージ（ある場合）

エラーコード

HTTP ステータス	説明
400	パラメーターがない、または無効です
401	API キーが無効、または指定されていません
403	残高不足、またはベータ版へのアクセス権がありません
413	入力が大きすぎます（画像が base64 エンコードで 5MB を超過）
429	レート制限に達しました
500	内部サーバーエラー

注意事項

• count の上限は 10 です。
• UI デザインの参考資料には、代わりに octen-design スキルを使用してください。このスキルは topic=design を指定してこのエンドポイントを呼び出し、参考画像をダウンロードして、デザインの summary／html_snippet を作成します。