Recursos · Contratos de Saída

Contratos de Saída Unificados

Uma especificação de contrato para produção que garante respostas estáveis entre provedores de texto, voz, imagem e vídeo.

Voltar à documentação Ir para o Contrato Canônico

Contrato de Resposta Canônico

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

Princípios de Design

Um único envelope para todas as modalidades e provedores.
Nomes de campo permanecem estáveis entre versões em tempo de execução.
Detalhes específicos do provedor devem ficar nos metadados, sem alterar a estrutura de nível superior.
Saídas ausentes de uma modalidade retornam arrays vazios, não mudanças na estrutura.
O campo success é obrigatório para um tratamento determinístico pelo cliente.

Referência de Campos

success: resultado booleano da operação.
content: saída principal legível por humanos.
provider: identificador normalizado do provider.
usage: objeto de contabilização normalizado.
metadata: diagnósticos e contexto de execução.
images/files/videos: arrays de saída por modalidade.
error: objeto de erro estruturado quando success=false.

Exemplos com Múltiplos Provedores

Resposta normalizada no estilo OpenAI

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

Resposta normalizada no 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": []
}

Regras de Compatibilidade do Cliente

A lógica de renderização do frontend deve depender da forma do envelope, não dos detalhes internos do provider.
Os clientes devem tolerar chaves de metadata desconhecidas para garantir compatibilidade futura.
Arrays vazios são saídas válidas para modalidades não aplicáveis.
O parsing deve privilegiar verificações explícitas de campos em vez de ramificações por provider.

Error Contract

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

Os payloads de erro devem incluir um código legível por máquina e uma mensagem legível por humanos.
Identificadores de rastreamento devem ser propagados para diagnóstico.
Respostas com success=false nunca devem reutilizar campos exclusivos de payloads de sucesso.
O status HTTP e o código de erro estruturado devem permanecer consistentes.