Recursos · Contratos de salida

Contratos de salida unificados

Una especificación de contrato para producción que mantiene las respuestas estables entre proveedores de texto, voz, imagen y vídeo.

Volver a la documentación Ir al contrato canónico

Contrato de respuesta canónica

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

Principios de diseño

Un único envoltorio para todas las modalidades y proveedores.
Los nombres de los campos permanecen estables entre versiones de tiempo de ejecución.
Los detalles específicos del proveedor se almacenan en los metadatos, no en cambios de la estructura de primer nivel.
Las salidas de modalidades ausentes devuelven matrices vacías, no cambios en la estructura.
La bandera success es obligatoria para un manejo determinista por parte del cliente.

Referencia de campos

success: resultado booleano de la operación.
content: salida principal legible por humanos.
provider: identificador normalizado del proveedor.
usage: objeto de contabilidad normalizado.
metadata: diagnósticos y contexto de ejecución.
images/files/videos: arreglos de salida por modalidad.
error: objeto de error estructurado cuando success=false.

Ejemplos de múltiples proveedores

Respuesta normalizada al estilo OpenAI

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

Respuesta normalizada al estilo 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": []
}

Reglas de compatibilidad del cliente

La lógica de renderizado del frontend debe depender de la forma del envoltorio, no de los detalles internos del proveedor.
Los clientes deben tolerar claves de metadata desconocidas para compatibilidad hacia adelante.
Las matrices vacías son salidas válidas para modalidades no aplicables.
El análisis debe preferir comprobaciones explícitas de campos en lugar de ramificaciones por proveedor.

Error Contract

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

Los payloads de error deben incluir un código legible por máquina y un mensaje legible por humanos.
Los identificadores de traza deben propagarse para fines de diagnóstico.
Las respuestas con success=false nunca deben reutilizar campos exclusivos del payload de éxito.
El estado HTTP y el código de error estructurado deben ser coherentes.