بحث الصور

آخر تحديث 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);