Risorse · Contratti di output

Contratti di output unificati

Una specifica di contratto per la produzione che mantiene le risposte stabili tra provider di testo, voce, immagine e video.

Torna alla documentazione Vai al contratto canonico

Contratto di risposta canonico

{
  "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": []
}

Principi di progettazione

Un unico involucro per tutte le modalità e i provider.
I nomi dei campi rimangono stabili tra le versioni di runtime.
I dettagli specifici del provider risiedono nei metadata, non in variazioni della struttura a livello superiore.
Le uscite per modalità mancanti ritornano array vuoti, non cambiamenti nella struttura.
Il flag success è obbligatorio per una gestione deterministica lato client.

Riferimento dei campi

success: risultato booleano dell'operazione.
content: output principale leggibile dall'uomo.
provider: identificatore normalizzato del provider.
usage: oggetto di rendicontazione normalizzato.
metadata: diagnostica e contesto di esecuzione.
images/files/videos: array di output per la modalità.
error: oggetto di errore strutturato quando success=false.

Esempi per più provider

Risposta normalizzata in stile OpenAI

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

Risposta normalizzata in stile Replicate

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

Regole di compatibilità per i client

La logica di rendering del frontend dovrebbe dipendere dalla forma dell'involucro, non dagli interni del provider.
I client devono tollerare chiavi metadata sconosciute per la compatibilità futura.
Gli array vuoti sono output validi per modalità non applicabili.
Il parsing dovrebbe preferire controlli espliciti sui campi rispetto a ramificazioni specifiche del provider.

Error Contract

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

I payload di errore devono includere un codice leggibile dalla macchina e un messaggio leggibile dall'uomo.
Gli identificatori di tracciamento dovrebbero essere propagati per la diagnostica.
Le risposte success=false non devono mai riutilizzare i campi presenti solo nei payload di successo.
Lo stato HTTP e il codice di errore strutturato devono rimanere coerenti.