Referensi REST API Pencarian Gambar

Titik Akhir:POST https://api.microsoft.ai/v3/search/images

Permintaan Sampel:

curl -X POST "https://api.microsoft.ai/v3/search/images" \
  -H "host: api.microsoft.ai" \
  -H "x-apikey: <Your key>" \
  -H 'content-type: application/json' \
  -d '{
    "query": "cats",
    "maxResults": 2,
    "language": "en",
    "region": "US"
  }'

Parameters

Parameter	Required	Type	Default	Description
query	Yes	string	-	String kueri pencarian. Panjang maksimum adalah 1000 karakter.
maxResults	No	integer	30	Jumlah maksimum hasil yang akan dikembalikan. Defaultnya adalah 30 dan nilai maksimum adalah 30.
language	No	string	"en"	Kode bahasa ISO 639-1 2 huruf untuk bahasa antarmuka dalam hasil pencarian. Lihat Bahasa yang Didukung untuk daftar lengkapnya.
region	No	string	"US"	Kode negara/wilayah 2 huruf tempat hasilnya harus berasal (misalnya "US", "JP", "CN"). Lihat Wilayah yang Didukung untuk daftar lengkapnya.
aspectRatio	No	string(enum)	-	Memfilter gambar menurut rasio aspek. Nilai: "persegi" (kira-kira 1:1), "lebar" (tinggi lebar > ), "tinggi" (lebar tinggi > ). Saat tidak diatur, tidak ada pemfilteran yang diterapkan.
color	No	string(enum)	-	Filter gambar menurut warna gambar. Nilai: "colorOnly" (hanya mengembalikan gambar warna), "monokrom" (hanya mengembalikan gambar hitam dan putih). Saat tidak diatur, tidak ada pemfilteran yang diterapkan.
safeSearch	No	string(enum)	"ketat"	Tingkat pemfilteran pencarian yang aman. Nilai: "off", "strict". Defaultnya adalah "ketat".
imageSize	No	string(enum)	-	Filter gambar menurut kategori ukuran. Nilai: "kecil" (<200x200px), "sedang" (lebar atau tinggi 200-500px), "besar" (lebar atau tinggi >=500px), "extraLarge" (>1024x768px). Juga dapat menggunakan batasan piksel (maxHeight, minHeight, maxWidth, minWidth) untuk batas kustom; batasan piksel lebih diutamakan daripada imageSize saat berkonflik. Saat tidak diatur, tidak ada pemfilteran yang diterapkan.
watermarkFree	No	Boolean	tidak benar	Kecualikan gambar dengan marka air. Nilai default adalah false.
maxHeight	No	integer	-	Tinggi gambar maksimum dalam piksel. Digunakan dengan imageSize untuk batas kustom.
minHeight	No	integer	-	Tinggi gambar minimum dalam piksel.
maxWidth	No	integer	-	Lebar gambar maksimum dalam piksel.
minWidth	No	integer	-	Lebar gambar minimum dalam piksel.

Header Permintaan

Field	Type	Description
host	string	Host untuk API AI Microsoft: api.microsoft.ai.
x-apikey atau Otorisasi	string	Kunci API Anda atau token akses Entra ID untuk autentikasi.
jenis konten	string	Jenis MIME isi permintaan. Gunakan application/json.

Jawaban

ImagesResponse

Field	Type	Description
imageResults	array ImageResult	Daftar hasil gambar.
instrumentationClickBase	string	URL Dasar untuk mengeklik permintaan ping. Tambahkan instrumentationSuffix nilai dari item hasil untuk membentuk URL ping lengkap. Hanya ada untuk aplikasi dengan bendera profil EnableInstrumentationPing. Catatan: Klik pengguna juga dapat dicatat menggunakan pengalihan URL. Ketika pengalihan diaktifkan, tidak ada tindakan yang diperlukan untuk mencatat klik Pengguna, dan instrumentationClickBase tidak akan disertakan dalam respons. Lihat Panduan instrumentasi untuk instruksi penyiapan.
instrumentationCitationBase	string	URL Dasar untuk permintaan ping log LLM. Tambahkan payload DATA untuk membentuk URL ping lengkap. Hanya ada untuk aplikasi dengan bendera profil EnableInstrumentationPing.
traceId	string	ID pelacakan untuk penelusuran kesalahan dan pelacakan.

ImageResult

Field	Type	Description
title	string	Judul gambar.
url	string	URL sumber gambar. Untuk pengguna Tiongkok dengan pengalihan URL diaktifkan, bidang ini sebagai gantinya berisi URL pengalihan yang sama dengan clickUrl.
domain	string	Host tujuan untuk hasilnya. Dikembalikan hanya untuk pengguna Tiongkok dengan pengalihan URL diaktifkan.
hostPageUrl	string	URL halaman web yang menghosting gambar.
caption	string	Deskripsi gambar yang dihasilkan.
width	integer	Lebar gambar, dalam piksel.
height	integer	Tinggi gambar, dalam piksel.
thumbnailUrl	string	URL sumber gambar mini gambar dari gambar.
lastUpdatedAt	string	Tanggal terakhir gambar yang diperbarui, mengikuti format ISO8601.
isAdult	Boolean	Menunjukkan apakah konten tersebut adalah konten dewasa.
clickUrl	string	Alihkan URL yang memproksi klik melalui Bing. Hanya ada saat pengalihan klik diaktifkan.
instrumentationSuffix	string	Akhiran untuk ditambahkan ke basis URL ping instrumentasi untuk item hasil ini. Digunakan sebagai nilai K untuk URL ping instrumentasi dan clickUrl pengalihan. Ada saat ping instrumentasi diaktifkan.

Kode Kesalahan

Kode Status	Kategori Kesalahan	Description	Penyebab Umum
200	Keberhasilan	Permintaan itu berhasil.	-
400	Permintaan Tidak Valid	Parameter permintaan tidak valid.	Bidang yang diperlukan hilang, nilai parameter tidak valid, JSON cacat
401	Unauthorized	Autentikasi gagal atau hilang.	Kunci API tidak valid, header x-apikey hilang
403	Forbidden	Kredensial yang valid tetapi izinnya tidak mencukup.	Kunci API tidak memiliki izin yang diperlukan
410	Hilang	HTTPS diperlukan.	Permintaan yang dibuat melalui HTTP alih-alih HTTPS
415	Tipe Media yang Tidak Didukung	Tipe isi tidak didukung.	Header tipe konten yang hilang atau salah
429	Terlalu Banyak Permintaan	Batas kecepatan terlampaui.	Terlalu banyak permintaan dalam jendela waktu
500	Kesalahan Server Internal	Kesalahan server tak terduga.	Masalah server sementara
503	Layanan Tidak Tersedia	Layanan untuk sementara tidak tersedia.	Pemeliharaan atau pemadaman sementara
504	Waktu Habis Gateway	Waktu permintaan berakhir.	Batas waktu layanan upstram

Untuk panduan penanganan kesalahan terperinci, lihat Penanganan Kesalahan.

---

Lihat juga:Pencarian | Video Pencarian | WebTelusuri | Pencarian | BeritaMCP