API compatível com OpenAI

API compatível com OpenAI

Endpoints /v1, chat completions, cabeçalhos, códigos de erro, streaming e cache.

O gateway oferece endpoints compatíveis com OpenAI na URL base /v1. Clientes OpenAI podem usar o gateway em vez do provedor.

Endpoints#

Método e caminhoFinalidade
POST /v1/chat/completionsChat completions estilo OpenAI, nativo ou por facade para backends Anthropic.
POST /v1/responsesRelay Responses API para SDKs recentes; adaptado para chat no mesmo pipeline.
POST /v1/embeddingsEmbeddings estilo OpenAI roteados ao provedor configurado.
GET /v1/modelsLista modelos registrados.

Aliases de rotas conhecidos permitem conectar SDKs e ferramentas existentes sem alterações.

Endpoint Gateway: imagens, áudio, arquivos, fine-tuning e lotes#

Interfaces adicionais compatíveis com OpenAI podem ser habilitadas além de chat, messages e embeddings. Desativadas por padrão; endpoint desligado retorna 404 endpoint_disabled. Configure em Settings -> Endpoint Gateway:

SuperfícieControleComportamento
/v1/images/generations, edits, variationsimagesInspeciona, mascara e comprime prompt JSON como chat; verifica metadados e usa cache sujeito à inspeção.
/v1/audio/speechaudioInspeciona entrada como prompt de chat e encaminha.
/v1/audio/transcriptions, translationspassthroughRelay multipart governado, injeção de chave e auditoria.
/v1/filesfilesDecodifica e inspeciona texto; bloqueia uploads com violações e permite binários.
/v1/fine_tuning/jobs, /v1/batchespassthroughRelay governado com injeção de chave e auditoria.

Pixels e formas de onda não são analisados, somente texto associado. O tipo de endpoint é registrado na transação.

Cabeçalhos#

CabeçalhoFinalidade
Authorization: Bearer [key]Autenticação do cliente e/ou chave upstream conforme o modo.
X-Agent-IDIdentidade do agente para acompanhamento, roteamento, risco e escopo do cache.
X-User-IdIdentidade do usuário; claims sub do token autenticado têm preferência.
x-aifw-cache-refreshIgnora consulta ao cache, mas permite gravar.

Solicitação padrão#

POST /v1/chat/completions
{
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Hello!" }
  ],
  "stream": false
}
CampoObservações
modelOpcional; se omitido, usa modelo padrão configurado.
messagesMensagens padrão; tool_calls/tool passam byte a byte.
streamtrue usa modo buffered ou live efetivo.

Códigos de erro#

Solicitações bloqueadas ou rejeitadas retornam HTTP 400 com erro estruturado:

{
  "error": {
    "message": "The transaction was intercepted and blocked by corporate AI security policy.",
    "type": "guardrail_violation",
    "code": "prompt_injection_detected",
    "details": { "policy_id": "BUILTIN-JAILBREAK", "timestamp": "2025-01-15T10:00:00Z" }
  }
}
CódigoSignificado
guardrail_violationBloqueado por regra integrada ou personalizada; inclui ID da política.
prompt_injection_detectedCorrespondência com jailbreak ou injeção.
semantic_rule_violation:ruleScore semântico excede limite de bloqueio.
model_disabledModelo registrado, porém desabilitado.
model_not_registeredModo estrito ativo e modelo não registrado.
backend_not_configuredModelo resolvido sem URL backend configurada.
default_policy_blockNenhuma regra correspondeu e ação padrão é block.

Respostas bloqueadas incluem X-Gateway-Security: Violated. Falhas de autenticação retornam 401; rotas desconhecidas, 404.

Streaming#

Com stream: true, respostas usam server-sent events e terminam com data: [DONE].

  • buffered (padrão): inspeciona a resposta completa antes de entregar tokens; violação retorna 400 antes da entrega.
  • stream: transmite tokens ao vivo; violação interrompe SSE com guardrail_violation. Tokens já entregues não podem ser retirados.

Cache#

Com escopo configurado, respostas podem vir do completion cache. Hits são registrados e o body passa novamente pela inspeção de resposta.

Relacionado

Próximas leituras#

Próximas leituras