Prüfbarer Ablauf

Veröffentlichungen und API

Ihr Board wird zum aufrufbaren Dienst.

Erstellen Sie einen visuellen Workflow, veröffentlichen Sie eine Version und rufen Sie diese aus Ihrer Anwendung, einem Skript oder Ihrem KI-Assistenten auf.

Ein Workflow, mehrere Einstiegspunkte

Ein Board verbindet Eingaben, Modelle und Ausgaben. Eine Veröffentlichung fixiert eine Version und legt fest, was Aufrufende übermitteln und erhalten. Der REST-API-Kanal macht diese Version per HTTP ausführbar.

Board → Veröffentlichung → Version → HTTP-Aufruf → Ergebnisse

Erstellen Sie einen visuellen Workflow, veröffentlichen Sie eine Version und rufen Sie diese aus Ihrer Anwendung, einem Skript oder Ihrem KI-Assistenten auf.

Die Veröffentlichung vorbereiten

1

Board erstellen und prüfen

Verbinden Sie Eingaben mit Verarbeitungsschritten und Ausgaben. Prüfen Sie das Ergebnis in Naquada, bevor Sie es Ihren Werkzeugen bereitstellen.

2

Ein- und Ausgaben wählen

Klicken Sie auf Veröffentlichen. Legen Sie die freigegebenen Felder, Aliase und Ausgaben fest. Die Aliase werden zu Schlüsseln im inputs-Objekt.

3

API aktivieren und Version veröffentlichen

Aktivieren Sie REST API unter Aktivierung. Veröffentlichen Sie die gewünschte Version für diesen Kanal. Änderungen am ursprünglichen Board verändern keine bereits fixierte Version.

4

Einen Schlüssel autorisieren

Erstellen Sie unter Veröffentlichungen → Schlüssel einen Schlüssel und erlauben Sie den Zugriff. Sowohl der Kanal als auch die Berechtigung des Schlüssels müssen aktiv sein.

Testen und produktiv einsetzen

Ein Sandbox-Schlüssel (ctr_sbx_…) liefert Testergebnisse ohne Modellausführung oder Guthabenverbrauch. Ein Production-Schlüssel (ctr_prd_…) führt den Workflow aus und verwendet das Guthaben des Eigentümers.

Schlüssel auf dem Server behalten

Speichern Sie ihn in Ihrer Geheimnisverwaltung, hier als NAQUADA_PUBLICATION_KEY. Browser oder Assistent rufen Ihren Dienst auf, der die Naquada-Anfrage authentifiziert. Der Schlüssel gehört nicht in öffentlichen Website-Code.

Den Workflow aufrufen

Ersetzen Sie my-workflow durch den Veröffentlichungs-Slug und version=1 durch eine für die API veröffentlichte Version. version ist Pflicht. Der Alias brief dient als Beispiel: verwenden Sie die Aliase Ihrer Veröffentlichung.

HTTP-Anfrage
curl --request POST \
  "https://api.naquada.tech/api/v1/generate/my-workflow?version=1" \
  --header "Authorization: Bearer $NAQUADA_PUBLICATION_KEY" \
  --header "Content-Type: application/json" \
  --data '{"inputs":{"brief":"A short product introduction"},"async_response":true}'

Mit async_response: true antwortet die API mit HTTP 202 und resultId. Bewahren Sie diese Kennung zur Statusverfolgung auf. Die Antwortwerte sind Beispiele.

202-Antwort · Beispiel
{
  "resultId": "12345678-1234-4234-8234-123456789abc",
  "status": "processing",
  "version": 1
}

Ergebnisse abrufen

Fragen Sie diese URL mit demselben Veröffentlichungsschlüssel ab. Die Antwort enthält status; freigegebene Ergebnisse erscheinen nach Abschluss in outputs. Setzen Sie im Beispiel NAQUADA_RESULT_ID auf die erhaltene resultId.

Ergebnis abfragen
curl "https://api.naquada.tech/api/v1/generate/results/$NAQUADA_RESULT_ID" \
  --header "Authorization: Bearer $NAQUADA_PUBLICATION_KEY"

processing: läuft · waiting_for_approval: menschliche Freigabe erforderlich · completed: fertig · partially_completed: Teilergebnisse · failed: fehlgeschlagen. Lassen Sie Abstand zwischen Abfragen und setzen Sie eine maximale Wartezeit.

Ohne async_response: true wartet der Aufruf höchstens zwei Minuten. Dauert die Verarbeitung länger, kann er mit 202 antworten. Auch diesen Fall muss Ihre Integration behandeln.

Dateien, Benachrichtigungen und Limits

Übergeben Sie für Dateifelder HTTPS-URLs in inputs. Mehrfachfelder akzeptieren ein URL-Array. Alternativ verwenden Sie multipart/form-data: data enthält die JSON-Hülle, Dateiteile heißen file_<alias>.

Richten Sie einen erlaubten Webhook für Abschlussmeldungen ein. Prüfen Sie X-Naquada-Signature anhand des unveränderten Anfragekörpers. Zustellungen können wiederholt werden: verarbeiten Sie Meldungen idempotent.

Tages- und Monatslimits sind unabhängig. Sie gelten nur, wenn sie mit einem positiven Wert aktiviert sind. Produktionsergebnisse verbrauchen das Budget des Veröffentlichungseigentümers.

Ihrem KI-Assistenten einen Workflow geben

Stellen Sie in Ihrem Dienst eine Funktion bereit: Sie empfängt die Felder, ruft die veröffentlichte Version auf, verfolgt resultId und gibt Ausgaben zurück. Ihr Assistent entscheidet über den Aufruf; Naquada führt das vorbereitete Board aus.

Verfügbare Verträge entdecken

Listen Sie erlaubte Veröffentlichungen auf und laden Sie den Detailvertrag mit der Veröffentlichungs-ID, nicht der ursprünglichen Board-ID. Beschreiben Sie mit diesen Feldern das Werkzeug für Ihren Assistenten.

Veröffentlichungen entdecken
curl "https://api.naquada.tech/api/v1/generate/boards" \
  --header "Authorization: Bearer $NAQUADA_PUBLICATION_KEY"

curl "https://api.naquada.tech/api/v1/generate/discovery/$NAQUADA_PUBLICATION_ID" \
  --header "Authorization: Bearer $NAQUADA_PUBLICATION_KEY"

Kontoschlüssel nqk_acc_… sind von Veröffentlichungsschlüsseln getrennt. Delegierte Aufrufe benötigen externalizations:invoke, Zugriff auf die Veröffentlichung sowie X-Naquada-Externalization-Key-Id mit der ID eines erlaubten Production-Schlüssels.

CLI- und MCP-Anleitung lesen