Sprach- und Bildsuche

Beide Endpunkte lösen dasselbe Problem: Der Nutzer hat keinen Suchbegriff, sondern eine Aufnahme oder ein Bild. Statt den Index multimodal zu indizieren, wird der Input in Text übersetzt und dann normal gesucht. Das hält den Index klein und die Ergebnisse nachvollziehbar — Sie sehen im Query-Log, was tatsächlich gesucht wurde.

SprachsucheCopy Anchor Link

AUDIO=$(base64 -w0 question.webm)

curl -sS -X POST "$AAC_API/indexes/documentation/voice" \
  -H "Authorization: Bearer $AAC_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"audio\": \"$AUDIO\",
    \"mime_type\": \"audio/webm\",
    \"language\": \"de\"
  }"

{
	"index": "documentation",
	"mode": "ai",
	"transcript": "was kostet der pro tarif",
	"found": 3,
	"hits": [
		{
			"id": "pricing",
			"score": 2711,
			"document": { "id": "pricing", "title": "Preise", "url": "https://example.com/pricing" },
			"highlights": [{ "field": "content", "snippet": "<mark>Pro</mark> kostet 29 USD im Monat" }]
		}
	],
	"latency_ms": 2860,
	"charged_cents": 0,
	"request_id": "req_2c4e6a8b0d2f4a6c8e0b2d4f"
}

Die resultierende Suche liefert immer 10 Treffer pro Seite; ein per_page gibt es hier nicht. Wollen Sie mehr oder weniger, rufen Sie /search mit dem transcript selbst auf.

mode sagt, wer transkribiert:

• ai — die Plattform transkribiert die Aufnahme mit der konfigurierten KI-Funktion und sucht anschließend nach dem erkannten Text.
• native — ein konfiguriertes Sprachmodell transkribiert die Aufnahme. Anschließend durchsucht dieselbe Pipeline wie bei Texteingaben den Index, mit Mandantenprüfung, Dokumentrechten, Schutz privater Felder und Kontingenten.

Ist beides nicht konfiguriert, kommt 503 VOICE_MODEL_NOT_CONFIGURED; ist die Engine zu alt für den Engine-Modus, 501 ENGINE_FEATURE_UNSUPPORTED. GET /capabilities zeigt features.voiceQuery.

Fehlerfälle: kein dekodierbares Audio ergibt 422 INVALID_AUDIO, eine Aufnahme ohne erkannte Sprache 422 EMPTY_TRANSCRIPTION — meist Stille oder Musik. Sehr große Payloads scheitern an 413 AUDIO_TOO_LARGE oder der Body-Grenze des Proxys.

transcript ist der eigentliche Gewinn: Loggen Sie ihn, dann sehen Sie Spracheingaben im Query-Log wie jeden anderen Suchbegriff, inklusive Null-Ergebnis-Alerts.

BildsucheCopy Anchor Link

curl -sS -X POST "$AAC_API/indexes/documentation/image" \
  -H "Authorization: Bearer $AAC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://cdn.example.com/screenshots/billing-panel.png",
    "hint": "Einstellungen Abrechnung",
    "per_page": 5
  }'

{
	"index": "documentation",
	"mode": "ai",
	"description": "Screenshot eines Abrechnungs-Panels mit Tarifauswahl und Guthabenanzeige",
	"model": "gpt-4o-mini",
	"found": 2,
	"hits": [
		{
			"id": "billing",
			"score": 1422,
			"document": { "id": "billing", "title": "Abrechnung", "url": "https://example.com/billing" }
		}
	],
	"latency_ms": 2140,
	"charged_cents": 0,
	"request_id": "req_7a9c1e3b5d7f9a1b3c5d7e9f"
}

description ist die vom Modell erzeugte Bildbeschreibung. Sie wird anschließend wie jede andere Suchanfrage ausgeführt — inklusive filter_by, Mandantenfilter und Highlighting. Es gibt keinen Vektor-Index über Bilder: Gesucht wird im Text, den das Modell aus dem Bild ableitet. Ein Produktfoto ohne beschreibenden Begleittext findet deshalb nichts.

Bei einer URL lädt der Server das Bild selbst; erlauben Sie in Firewall oder Egress-Proxy nur die Hosts, die Sie tatsächlich brauchen. Bei Base64 gilt eine Obergrenze von 12 MB.

Wann sich das lohntCopy Anchor Link

• Support und Doku: „Wo ist diese Einstellung?“ mit Screenshot ist eine reale Anfrage, die Stichwortsuche nicht beantwortet.
• Kataloge: Ein Foto eines Produkts ohne Typenschild.
• Barrierefreiheit: Spracheingabe für Nutzer, die nicht tippen wollen oder können.

Wann nicht: Wenn Ihre Inhalte keine beschreibenden Texte haben, hilft auch die Bildbeschreibung nicht — sie sucht im Text, nicht in den Bildern. Und wenn Latenz kritisch ist: Beide Endpunkte brauchen ein Modell, latency_ms liegt realistisch bei 2–4 Sekunden.

KostenCopy Anchor Link

Beide Endpunkte messen die Modell-Tokens als ai_tokens im Tarifkontingent. charged_cents ist nur bei Überschreitung ungleich null. Ein Sprachaufruf kostet typischerweise ein paar Cent-Bruchteile, ein Bildaufruf mehr — prüfen Sie GET /billing/usage, bevor Sie Sprachsuche in einem Widget mit vielen Nutzern aktivieren.

Das fertige Widget bringt Spracheingabe bereits mit: showVoice: true in den Embed-Einstellungen aktiviert InstantSearch voiceSearch, das die Browser-Spracherkennung nutzt und damit gar keine Serverkosten erzeugt. Die hier beschriebenen Endpunkte sind für eigene Oberflächen und für Clients ohne Web Speech API.