Ressourcen · Ausgabeverträge

Einheitliche Ausgabeverträge

Eine Spezifikation für Produktionsverträge, die Antworten über Text-, Sprach-, Bild- und Videoanbieter hinweg stabil hält.

Zurück zur Dokumentation Zum kanonischen Vertrag springen

Kanonischer Antwortvertrag

{
  "success": true,
  "content": "Primary human-readable output",
  "provider": "openai",
  "usage": {
    "input_tokens": 120,
    "output_tokens": 64
  },
  "metadata": {
    "model": "gpt-x",
    "latency_ms": 540,
    "trace_id": "trc_123"
  },
  "images": [],
  "files": [],
  "videos": []
}

Designprinzipien

Ein Envelope für alle Modalitäten und Anbieter.
Feldnamen bleiben über Laufzeitversionen hinweg stabil.
Anbieterspezifische Details gehören in die Metadaten, nicht zu Änderungen der Top-Level-Struktur.
Fehlende Modalitätsausgaben liefern leere Arrays zurück, keine Strukturänderungen.
Das success-Flag ist für deterministisches Client-Verhalten Pflicht.

Feldreferenz

success: boolesches Ergebnis der Operation.
content: primäre, für Menschen lesbare Ausgabe.
provider: normalisierter Anbieterkennzeichner.
usage: normalisiertes Abrechnungsobjekt.
metadata: Diagnose- und Ausführungskontext.
images/files/videos: Ausgabe-Arrays der Modalitäten.
error: strukturiertes Fehlerobjekt, wenn success=false.

Beispiele für mehrere Anbieter

Im OpenAI-Stil normalisierte Antwort

{
  "success": true,
  "content": "Generated response",
  "provider": "openai",
  "usage": { "input_tokens": 90, "output_tokens": 52 },
  "metadata": { "latency_ms": 480 },
  "images": [],
  "files": [],
  "videos": []
}

Im Replicate-Stil normalisierte Antwort

{
  "success": true,
  "content": "Image generation completed",
  "provider": "replicate",
  "usage": { "input_tokens": 0, "output_tokens": 0 },
  "metadata": { "duration_ms": 2300 },
  "images": [{ "url": "https://..." }],
  "files": [],
  "videos": []
}

Client-Kompatibilitätsregeln

Die Rendering-Logik des Frontends sollte von der Envelope-Form abhängen, nicht von den Interna der Anbieter.
Clients müssen unbekannte Metadaten-Schlüssel für Vorwärtskompatibilität tolerieren.
Leere Arrays sind gültige Ausgaben für nicht anwendbare Modalitäten.
Das Parsen sollte explizite Feldprüfungen gegenüber Anbieter-Verzweigungen bevorzugen.

Error Contract

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request payload",
    "details": {}
  },
  "provider": "system",
  "metadata": {
    "trace_id": "trc_123"
  }
}

Fehler-Payloads müssen einen maschinenlesbaren Code und eine für Menschen lesbare Nachricht enthalten.
Trace-Identifikatoren sollten für die Diagnose weitergegeben werden.
Antworten mit success=false dürfen niemals Felder wiederverwenden, die ausschließlich in Erfolgspayloads verwendet werden.
HTTP-Status und strukturierter Fehlercode müssen konsistent bleiben.