Playground (Simulador)

24. Playground (Simulador)#

POST/v1/playground/generate-payload#

Gera um body de exemplo via OpenAI para o endpoint informado. Usado pelo simulador da Console (botao "🎲 Outro exemplo"). Resposta cacheada por 7 dias (cache hit não gasta budget). Modelos default: gpt-5.4-nano (texto) + gpt-image-1-mini (imagem).

Este endpoint não e escopado por instância — a rota e /v1/playground/generate-payload, registrada fora do grupo /v1/instances/{instanceId}/contacts.

Auth: Todos autenticados (JWT ou API Key)

Request:

json 
{
  "endpoint": "messages/text",
  "context": "casual"
}
Campo Tipo Obrigatório Descricao
endpoint string sim "messages/text", "messages/image", "messages/audio", "messages/document", "messages/sticker", "messages/video", "messages/poll", "messages/template". Outros valores retornam 400 PLAYGROUND_UNSUPPORTED_KIND.
context string não "casual" (default), "business", ou "friendly". Influencia o tom.

Resposta 200:

json 
{
  "body": {"text": "Tudo certo, me confirma quando puder?"},
  "generation_id": "gen_a1b2c3d4e5f6...",
  "cached": false
}
Campo Tipo Descricao
body object Partial body — o caller faz merge com a template existente. Para messages/image/video/sticker, contem media_url apontando para R2/S3 controlado pela Catcher (nunca URL OpenAI/Meta).
generation_id string ID curto para correlação em logs (cache hits e misses compartilham o mesmo ID quando o prompt e identico).
cached bool true quando o body veio do cache (sem call ao OpenAI).

Erros:

  • 503 PLAYGROUND_DISABLED — OPENAI_API_KEY não configurado neste servidor
  • 429 PLAYGROUND_BUDGET_EXCEEDED — limite diário de gasto atingido (default $10/dia)
  • 429 PLAYGROUND_RATE_LIMITED — rate limit per-user atingido (30/min ou 200/dia)
  • 400 PLAYGROUND_UNSUPPORTED_KIND — endpoint não reconhecido

Nota de seguranca: quando endpoint envolve imagem, a Catcher baixa a imagem do OpenAI, faz upload para o storage controlado (S3/R2 público ou endpoint autenticado), e devolve apenas a URL Catcher. Nunca expomos URL do OpenAI direto para o consumidor — alinha com a disciplina de proxy/CDN (lesson #29).