Eine API für alle KI-Antwort-Engines

Senden Sie mit einer einzigen Anfrage einen Prompt an jede unterstützte KI-Engine und erhalten Sie die Antwort als strukturiertes JSON, per Webhook oder Abfrage.

Was Sie erhalten

• Ein Endpoint, POST /v1/async/task, für alle Engines. Wählen Sie die Engine mit taskType und den Markt mit country.
• Dieselbe Hülle für jede Engine: id, status und Zeitstempel der Aufgabe umschließen eine engine-spezifische response.
• Ergebnisse so, wie Sie es möchten: ein Webhook an Ihren Server, sobald eine Aufgabe fertig ist, oder GET /v1/async/task/{id}, wann immer Sie bereit sind.
• Sichere Wiederholungen mit idempotencyKey: Derselbe Schlüssel liefert erneut die Aufgabe, die Sie bereits angelegt haben.

So funktioniert es

KI-Engines brauchen Sekunden bis Minuten für eine Antwort, deshalb wird jede Anfrage zu einer dauerhaft gespeicherten Aufgabe. Eine Aufgabe wechselt von QUEUED zu PROCESSING und endet als COMPLETED mit der Antwort oder als FAILED mit dem Grund. Bei einem vorübergehenden Engine-Fehler kehrt die Aufgabe in die Warteschlange zurück und wird erneut versucht, sodass kurze Störungen behoben sind, bevor sie Sie erreichen.

Mit webhook.url senden wir die fertige Aufgabe an Ihren Server mit bis zu fünf Zustellversuchen innerhalb von etwa 30 Minuten. Fertige Aufgaben bleiben außerdem 24 Stunden lang abrufbar, sodass Webhook und Abfrage zusammen jedes Ergebnis abdecken.

Einsatzbereiche

• Prüfen Sie die Sichtbarkeit Ihrer Marke aus Ihrem eigenen Backend in beliebigem Rhythmus.
• Senden Sie einen Prompt an mehrere Engines und vergleichen Sie die Antworten nebeneinander.
• Lange Jobs bleiben einfach: absenden, weiterarbeiten und das Ergebnis per Webhook erhalten.

Anfrage senden

Senden Sie die Anfrage mit Ihrem API-Schlüssel im Header Authorization.

curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "CHATGPT",
    "payload": {
      "prompt": "Best coffee shops near me for working on a laptop",
      "country": "US"
    },
    "webhook": { "url": "https://your-server.example.com/hooks/querying" },
    "idempotencyKey": "laptop-cafes-us-0001"
  }'

Felder der Anfrage

taskTypestringPflicht

Die Engine, die die Aufgabe ausführt, etwa CHATGPT oder GOOGLE.

payloadobjectPflicht

Die Eingabe für die Engine: prompt oder query, dazu country und die Optionen der Engine.

webhook.urlstring

Eine HTTPS-Adresse Ihres Servers. Die fertige Aufgabe wird dorthin gesendet, sobald sie abgeschlossen ist.

idempotencyKeystring

Ihre eigene ID für die Anfrage. Jeder Schlüssel erzeugt pro Konto genau eine Aufgabe, ein wiederholter Versand bleibt also eine Aufgabe.

Antwort

Der Aufruf antwortet sofort mit der Aufgabe im Status QUEUED. credits bleibt bei 0, bis die Aufgabe fertig ist, und idempotencyKey kommt so zurück, wie Sie es gesendet haben.

{
  "success": true,
  "task": {
    "id": "…",
    "taskType": "CHATGPT",
    "status": "QUEUED",
    "priority": 1,
    "createdAt": "…",
    "idempotencyKey": "laptop-cafes-us-0001"
  },
  "credits": { "creditsToCharge": 0, "creditsCharged": 0 }
}

Ergebnis abholen

Rufen Sie die Aufgabe alle paar Sekunden mit GET /v1/async/task/{id} ab, bis status COMPLETED oder FAILED ist. Ergebnisse bleiben 24 Stunden nach Abschluss abrufbar.

curl https://api.querying.ai/v1/async/task/$TASK_ID \
  -H "Authorization: Bearer $QUERYING_API_KEY"

Eine fertige Aufgabe enthält die abgerechneten credits und die response der Engine. Diese ist echt, für die Lesbarkeit gekürzt.

{
  "success": true,
  "task": {
    "id": "e5aba119-a26e-4f82-a965-35c9234a428b",
    "taskType": "CHATGPT",
    "status": "COMPLETED",
    "createdAt": "2026-10-02T15:41:03.858Z"
  },
  "credits": { "creditsToCharge": 2, "creditsCharged": 2 },
  "response": {
    "text": "Here are several **nearby cafés that look particularly suitable for laptop work**, based on current local listings and work-friendly details:\n…",
    "sources": [
      {
        "position": 1,
        "url": "https://awifiplace.com/cities/new-york",
        "label": "Best Coffee Shops to Work in New York (2026) | 103 Cafes with WiFi"
      }
    ],
    "searchQueries": [
      "best coffee shops for laptop work near me wifi outlets"
    ]
  }
}

task.statusstring

QUEUED, PROCESSING, dann COMPLETED mit der Antwort oder FAILED mit error.

credits.creditsChargedinteger

Für die fertige Aufgabe berechnete Credits. Eine fehlgeschlagene Aufgabe kostet 0.

Webhooks

Mit webhook.url kommt die fertige Aufgabe als POST auf Ihrem Server an, mit denselben task, credits und response wie beim Abfragen. Eine fehlgeschlagene Aufgabe kommt genauso an, mit response.error und 0 abgerechneten Credits. Drei Header signieren jede Zustellung:

querying-webhook-idstring

Die Aufgaben-ID. Jede Zustellung kommt mindestens einmal an, nutzen Sie sie also, um Wiederholungen auszusortieren.

querying-webhook-timestampstring

Unix-Sekunden zum Zeitpunkt der Signatur. Akzeptieren Sie Zustellungen, die in den letzten 5 Minuten signiert wurden.

querying-webhook-signaturestring

v1, gefolgt vom base64-kodierten HMAC-SHA256 von {id}.{timestamp}.{body}, mit dem SHA-256-Digest Ihres API-Schlüssels als Schlüssel.

Prüfen Sie die Signatur am unveränderten Body, bevor Sie ihn parsen, und nehmen Sie die Zustellung an, wenn sie passt:

import base64
import hashlib
import hmac
import os
import time


def verify_webhook(headers, body: bytes) -> bool:
    """body is the raw request body, before json.loads."""
    task_id = headers["querying-webhook-id"]
    timestamp = headers["querying-webhook-timestamp"]
    key = hashlib.sha256(os.environ["QUERYING_API_KEY"].encode()).digest()
    signed = f"{task_id}.{timestamp}.".encode() + body
    digest = hmac.new(key, signed, hashlib.sha256).digest()
    expected = "v1," + base64.b64encode(digest).decode()
    given = headers.get("querying-webhook-signature", "")
    fresh = abs(time.time() - int(timestamp)) <= 300
    return fresh and hmac.compare_digest(expected, given)

Antworten Sie innerhalb von 30 Sekunden mit einem 2xx-Status. Bei jeder anderen Antwort oder nach 30 Sekunden folgt eine erneute Zustellung nach 2, 4, 8 und 16 Minuten, insgesamt fünf Versuche, alle mit derselben querying-webhook-id.

Fehler

Eine abgelehnte Anfrage antwortet sofort mit success gleich false und einem error mit code, message und bei Feldfehlern details. Sie bleibt außerhalb der Warteschlange und kostet 0 Credits.

VALIDATION_ERRORHTTP 400

Ein Feld fehlt oder liegt außerhalb des erlaubten Bereichs. details nennt das Feld.

MISSING_API_KEYHTTP 401

Der Header Authorization fehlt, oder sein Schlüssel ist unbekannt, abgelaufen oder widerrufen.

INSUFFICIENT_CREDITSHTTP 402

Das Guthaben liegt unter dem Preis der Aufgabe. Laden Sie Credits auf oder wechseln Sie den Plan und senden Sie erneut.

KEY_SCOPE_DENIEDHTTP 403

Die Engine liegt außerhalb der Erlaubten Engines des Schlüssels. Nutzen Sie einen anderen Schlüssel oder ergänzen Sie die Engine unter Schlüssel verwalten.

RESOURCE_ALREADY_EXISTSHTTP 409

Auf Ihrem Konto gibt es bereits eine Aufgabe mit diesem idempotencyKey, das Senden bleibt also bei einer Aufgabe. Im Batch zählt der Eintrag als Erfolg.

PAYLOAD_TOO_LARGEHTTP 413

Der Body ist größer als 1 MiB, bei einem Batch größer als 8 MiB.

REGION_UNSUPPORTEDHTTP 422

country liegt außerhalb der Länderliste der Engine. Erneutes Senden ergibt dasselbe, daher ist details.retryable gleich false.

PLAN_CONCURRENCY_LIMITHTTP 429

Ihre wartenden und laufenden Aufgaben haben das Limit des Plans erreicht: 2 im kostenlosen Plan, 10 bei Basic, 25 bei Pro, 50 bei Scale und 100 bei Max. Senden Sie nach Retry-After Sekunden erneut.

KEY_DAILY_CREDIT_LIMITHTTP 429

Der Schlüssel hat sein Tägliches Credit-Limit aufgebraucht. Retry-After reicht bis zur nächsten Mitternacht UTC.

QUEUE_BACKPRESSUREHTTP 429

Die Warteschlange der Engine ist gerade voll. Senden Sie nach Retry-After Sekunden erneut.

Preis

Jede Engine hat ihren eigenen Credit-Preis, und eine Aufgabe wird bei Abschluss berechnet. Eine fehlgeschlagene Aufgabe gibt ihre reservierten Credits wieder frei.