画像検索

最終更新 July 20, 2026

画像検索結果を JSON で返す。

TEXT

GET /v1/images

有効な API キー、有効なメンバーシップ、利用可能な API クレジットが必要である。

クエリパラメータ

名前	型	必須	既定	説明
`q`	string	はい	—	検索クエリ。
`safe`	string	いいえ	`on`	セーフサーチのレベル: `off`、`on`。
`gl`	string	いいえ	(自動)	二文字の地域/国コード(例: `us`、`gb`、`jp`)。
`hl`	string	いいえ	(自動)	二文字の言語コード(例: `en`、`es`、`ja`)。
`time`	string	いいえ	`any`	新しさのフィルター: `any`、`hour`、`day`、`week`、`month`、`year`。
`num`	integer	いいえ	(プロバイダーの既定)	希望する結果数。5〜100 にクランプされる(範囲外 → 20)。

レスポンス

各バーティカルのエンドポイントはひとつの結果形状を共有し、そのバーティカルに関係するフィールドだけが埋められる。画像の場合は thumbnail と meta(ソース)が最も役立ち、price と extra は通常 null である。

JSON

{
  "query": "golden gate bridge",
  "kind": "image",
  "results": [
    {
      "title": "Golden Gate Bridge at sunset",
      "url": "https://example.com/photos/ggb.jpg",
      "description": null,
      "thumbnail": "https://example.com/photos/ggb-thumb.jpg",
      "price": null,
      "meta": "example.com",
      "extra": null
    }
  ]
}

フィールド	型	説明
`query`	string	実行されたクエリ。
`kind`	string	このエンドポイントでは常に `image`。
`results[].title`	string	画像のタイトル / キャプション。
`results[].url`	string	フル画像(またはそのページ)の URL。
`results[].description`	string \| null	説明(利用できる場合)。
`results[].thumbnail`	string \| null	サムネイル画像の URL。
`results[].meta`	string \| null	ソース / ホスト。
`results[].price`	string \| null	画像では使わない。
`results[].extra`	string \| null	画像では使わない。

例

cURL

curl -G "https://api.suede.io/v1/images" \
  -H "Authorization: Bearer $SUEDE_API_KEY" \
  --data-urlencode "q=golden gate bridge" \
  --data-urlencode "safe=on"

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new("Bearer", Environment.GetEnvironmentVariable("SUEDE_API_KEY"));
var url = "https://api.suede.io/v1/images?q=" + Uri.EscapeDataString("golden gate bridge");
Console.WriteLine(await http.GetStringAsync(url));

JavaScript

const res = await fetch(
  "https://api.suede.io/v1/images?q=" + encodeURIComponent("golden gate bridge"),
  { headers: { Authorization: `Bearer ${process.env.SUEDE_API_KEY}` } },
);
const data = await res.json();
for (const r of data.results) console.log(r.thumbnail);