Vom Konto zur ersten Antwort.

Entwicklerreferenz: App-Schnittstelle

In vier Schritten zur ersten Antwort.

Die HACCA App-API nimmt Textnachrichten entgegen und liefert eine vollständige JSON-Antwort. Jede Anfrage läuft über das Bezahlabo und die Kontingente des Kontos, dem der Schlüssel gehört: bei einem eigenen Programm über dein Konto, bei einer App für andere über das Konto jeder Person (zwei Wege der Anbindung). Für eine Integration mit größerem Lastprofil stimmen wir den Umfang im Unternehmenspilot ab.

1. Konto anlegen oder anmelden

   Melde dich unter hacca.ai/app an, oder lege dort mit „Konto erstellen“ ein neues Konto an.

2. Tarif ab Starter wählen

   Schlüssel für Apps gibt es ab dem Tarif Starter, die Tarife stehen unter Preise. Im Gratistarif zeigen die Einstellungen statt des Knopfs zum Erstellen einen Hinweis auf den Tarif, und die Schnittstelle antwortet mit 403. HACCA liest den Tarif bei jeder Anfrage neu: Endet das Bezahlabo, scheitert schon die nächste Anfrage.

3. Schlüssel erstellen

   Wähle in den Einstellungen im Abschnitt „Schlüssel für Apps“ den Knopf „Schlüssel für S&S Code erstellen“. Der Schlüssel gilt für jede App und jedes eigene Programm, nicht nur für S&S Code. Er beginnt mit hacca_, gilt ein Jahr und trägt die Berechtigung chat:write. HACCA zeigt ihn nur dieses eine Mal: „Kopieren“, sicher hinterlegen, dann „Fertig“.

4. Schlüssel hinterlegen und die erste Anfrage senden

   Die Beispiele lesen HACCA_API_KEY aus der Umgebung. Hinterlege den Wert auf deinem Server oder in einem geschützten Schlüsselspeicher. Binde einen Unternehmensschlüssel nicht in öffentliches Browser-JavaScript ein (HACCA erlaubt Browser-Aufrufe nur von hacca.ai) und schreibe ihn nicht in Quellcode oder Logs. Gesendet wird ein POST an den Endpunkt im Beispiel darunter, mit dem Schlüssel im Kopf Authorization: Bearer hacca_…; ein Login-Cookie ist nicht nötig.

curl --fail-with-body \
  --connect-timeout 10 --max-time 240 \
  https://hacca.ai/v1/ext/chat/completions \
  -H "Authorization: Bearer ${HACCA_API_KEY:?Schlüssel fehlt}" \
  -H "Content-Type: application/json" \
  --data '{"messages":[{"role":"user","content":"Nenne drei Prüfungen vor einem App-Launch."}],"max_tokens":512,"stream":false}'

Kommt HTTP 200 mit einem Antworttext zurück, steht die Verbindung. Den Aufbau der Antwort zeigt die Beispielantwort, jeden Fehlercode erklärt die Fehlertabelle. Die Beispiele senden jeweils genau eine Anfrage. 240 Sekunden sind ein gewählter Client-Timeout, keine zugesagte Antwortzeit.

Zwei Wege der Anbindung.

Eigenes Programm mit deinem Schlüssel. Du erstellst den Schlüssel in deinem HACCA-Konto und hinterlegst ihn auf deinem Server. Alle Anfragen laufen über deinen Tarif und deine Kontingente. Für dein Konto laufen höchstens zwei Anfragen gleichzeitig, auch mit mehreren Schlüsseln. Ein Angebot für eigene Kunden oder mehr Last stimmen wir im Unternehmenspilot ab.

Eine Webseite kann HACCA nicht direkt aus dem Browser aufrufen, denn HACCA erlaubt das (CORS) nur von hacca.ai; auf deiner eigenen Domain ruft deshalb dein Server HACCA auf.

App mit den Schlüsseln ihrer Nutzer. Jede Person erstellt in ihrem eigenen HACCA-Konto einen Schlüssel für deine App und fügt ihn dort ein. Der Schlüssel bleibt auf ihrem Gerät, im geschützten Speicher wie dem Schlüsselbund unter iOS oder dem Keystore unter Android, und geht nicht an deinen Server; sollen Anfragen über deinen Server laufen, nimm den ersten Weg mit deinem eigenen Schlüssel. Eine Webseite fällt unter den ersten Weg.

Jede Anfrage läuft über den Tarif dieser Person; sie braucht dafür einen Tarif ab Starter. Je Konto laufen höchstens zwei Anfragen gleichzeitig. Zum Entwickeln und Testen brauchst du selbst ein Konto ab Starter.

Diesen Hinweis kann deine App zeigen: „Erstelle in HACCA unter Einstellungen im Abschnitt Schlüssel für Apps einen eigenen Schlüssel für diese App und füge ihn hier ein. Dort siehst du, wann er zuletzt benutzt wurde, und kannst ihn jederzeit widerrufen.“

Python und Node.js.

Beide Beispiele verwenden die Standardbibliothek und geben bei HTTP-Fehlern nur Status und Fehlercode aus. Schlüssel und Nachrichtentexte werden dabei nicht protokolliert.

import json
import os
from urllib.error import HTTPError
from urllib.request import Request, urlopen

body = {
    "messages": [{"role": "user", "content": "Nenne drei Prüfungen vor einem App-Launch."}],
    "max_tokens": 512,
    "stream": False,
}
request = Request(
    "https://hacca.ai/v1/ext/chat/completions",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + os.environ["HACCA_API_KEY"],
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urlopen(request, timeout=240) as response:
        result = json.load(response)
except HTTPError as exc:
    try:
        failure = json.loads(exc.read())
        code = failure.get("error", "unbekannt")
    except (ValueError, AttributeError):
        code = "keine_json_antwort"
    raise SystemExit(f"HACCA HTTP {exc.code}: {code}") from None

choice = result["choices"][0]
print(choice["message"]["content"])
if choice["finish_reason"] == "length":
    print("Antwort gekürzt: Aufgabe eingrenzen oder Ausgabebudget prüfen.")

const key = process.env.HACCA_API_KEY;
if (!key) throw new Error("HACCA_API_KEY fehlt");

const response = await fetch("https://hacca.ai/v1/ext/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    messages: [{ role: "user", content: "Nenne drei Prüfungen vor einem App-Launch." }],
    max_tokens: 512,
    stream: false,
  }),
  signal: AbortSignal.timeout(240_000),
});

const result = await response.json().catch(() => null);
if (!response.ok) {
  throw new Error(`HACCA HTTP ${response.status}: ${result?.error ?? "keine_json_antwort"}`);
}
if (!result?.choices?.[0]?.message) throw new Error("Unerwartete Antwort");
const choice = result.choices[0];
console.log(choice.message.content);
if (choice.finish_reason === "length") console.log("Antwort gekürzt: Aufgabe eingrenzen.");

Netzwerkfehler und Timeouts musst du zusätzlich im Ablauf deiner Anwendung behandeln. Der Python-Timeout begrenzt Netzwerkoperationen; die Node.js-Abbruchfrist betrifft den Client. Ein Client-Abbruch kann eine bereits gestartete Verarbeitung auf dem Server weiterlaufen lassen.

Das Anfrageformat.

Die Gesamtlänge aller messages[].content-Texte darf 64.000 Zeichen nicht überschreiten. Das ist eine Zeichengrenze, keine Token- oder Dateigrößengrenze. Bildblöcke, Dateiuploads und Werkzeugaufrufe gehören nicht zu diesem Vertrag.

Übermittle den benötigten bisherigen Nachrichtenverlauf selbst in messages. Dieser Endpunkt öffnet keinen Workspace und lädt keine Chat-Historie oder Wissensquellen aus deinem Chat nach.

Eine erfolgreiche Antwort.

Bei HTTP 200 enthält choices[0].message.content den Antworttext. Das Feld model nennt das tatsächlich verwendete Modell. Der Antwortheader X-HACCA-Paket nennt den für den Aufruf gelesenen Tarif.

{
  "id": "chatcmpl-beispiel1234",
  "object": "chat.completion",
  "created": 1791676800,
  "model": "gpt-4.1-nano",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Prüfe Anmeldung, Fehlerfälle und Datenschutz."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 12, "completion_tokens": 8, "total_tokens": 20}
}

finish_reason: "length" kennzeichnet eine am Ausgabebudget gekürzte Antwort. Weitere Abschlussgründe können vom Modell kommen. Behandle die Antwort dann entsprechend; ergänze fehlenden Inhalt nicht stillschweigend. usage beschreibt Tokenverbrauch und ist kein Rechnungsbetrag oder Beleg für eine Einsparung.

Fehler richtig unterscheiden.

Prüfe zuerst den HTTP-Status, dann error. Fachliche API-Fehler liefern den Fehlercode und message direkt auf der obersten JSON-Ebene. detail und agent_action sind optional. Texte können sich ändern; verzweige nicht auf ihren genauen Wortlaut.

{
  "error": "auth.token_invalid",
  "message": "Invalid or expired API key"
}

Ein Proxy- oder Infrastrukturfehler kann auch einen anderen Status oder eine Antwort ohne JSON liefern. Verwende deshalb einen Ausweichpfad für unerwartete Antworten und protokolliere keine Schlüssel oder vertraulichen Eingabetexte.

Limits, Wiederholungen und Schlüsselwechsel.

Parallelität: Plane höchstens zwei laufende Anfragen für dasselbe HACCA-Konto ein. Mehrere App-Schlüssel schaffen dafür kein zusätzliches Kontingent. Zusätzlich gilt eine konfigurierbare Anfragedrosselung; die Standardkonfiguration beträgt 60 Anfragen pro Minute am Endpunkt. Bei App-Schlüsseln zählt diese Drosselung nach Client-IP: Zugänge hinter derselben Adresse können sich die Grenze teilen. Die wirksame Produktionsgrenze wird im Pilot bestätigt.

Wiederholungen: Werte einen vorhandenen Retry-After-Header aus. Er kann eine Wartezeit in Sekunden oder ein HTTP-Datum enthalten. Nicht jeder 429- oder 503-Pfad liefert diesen Header. Ohne Header kannst du bei vorübergehenden Fehlern begrenztes Backoff mit zufälliger Streuung verwenden. Bei quota.exceeded, 400, 401, 403, 413 oder 422 ist zunächst eine Korrektur nötig.

Abbruch und Kosten: Ein Timeout oder Verbindungsabbruch bestätigt nicht, dass der Server den Auftrag verworfen hat. Ein begonnener Modellaufruf kann zu Ende laufen und Verbrauch buchen. Der Endpunkt bietet derzeit keine Idempotenzgarantie; ein erneutes POST kann einen weiteren kostenpflichtigen Aufruf auslösen. Auch eine leere Antwort mit HTTP 502 kann nach den geltenden Erstattungsgrenzen berechnet werden. Der konkrete Fehlertext beschreibt den Ausgang oder einen unbestätigten Rückbuchungsversuch.

Schlüssel verwalten: In den Einstellungen kannst du Schlüssel ansehen und widerrufen. Dort erstellte Schlüssel gelten ein Jahr; über die Verwaltung in der Tabelle unten angelegte gelten ohne Angabe 90 Tage, wählbar sind 1 bis 365 Tage. Pro Nutzer sind bis zu zehn Schlüssel vorgesehen. Plane einen Wechsel vor dem angegebenen Ablaufdatum.

Widerruf: Ein erfolgreich widerrufener Schlüssel wird bei der nächsten Schlüsselprüfung abgewiesen. Bereits gestartete Aufrufe können weiterlaufen. Beim geplanten Wechsel erst den neuen Schlüssel im geschützten Speicher hinterlegen, die Verbindung prüfen und anschließend den alten widerrufen. Bei einem offengelegten Schlüssel zuerst den betroffenen Zugang widerrufen.