Documentação da API: Criar Saídas Estruturadas

Descrição da API

Dado um prompt (Prompt), o modelo retornará uma ou mais respostas de preenchimento (completion) previstas e possui suporte para forçar o modelo a gerar dados estruturados de acordo com um JSON Schema especificado.

Documentação Oficial de Referência: OpenAI Structured Outputs

Informações Básicas da API

• Método da Requisição: POST
• Endpoint da Requisição: https://api.codingplanx.ai/v1/chat/completions
• Formato de Dados: application/json

---

Cabeçalhos da Requisição (Headers)

---

Corpo da Requisição (Request Body)

Exemplo de Requisição (Request Example)

{
  "model": "gpt-4.1-2025-04-14",
  "messages": [
    {
      "role": "system",
      "content": "Determine if the user input violates specific guidelines and explain if they do."
    },
    {
      "role": "user",
      "content": "How do I prepare for a job interview?"
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "content_compliance",
      "description": "Determines if content is violating specific moderation rules",
      "schema": {
        "type": "object",
        "properties": {
          "is_violating": {
            "type": "boolean",
            "description": "Indicates if the content is violating guidelines"
          },
          "category": {
            "type": ["string", "null"],
            "description": "Type of violation, if the content is violating guidelines. Null otherwise.",
            "enum": ["violence", "sexual", "self_harm"]
          },
          "explanation_if_violating": {
            "type": ["string", "null"],
            "description": "Explanation of why the content is violating"
          }
        },
        "required": ["is_violating", "category", "explanation_if_violating"],
        "additionalProperties": false
      },
      "strict": true
    }
  }
}

---

Corpo da Resposta (Response Body)

Exemplo de Resposta (Response Example)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "\r
\r
Hello there, how may I assist you today?"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

---

Perguntas Frequentes (FAQs)

1. O que é response_format e como garantir que o modelo produza um JSON rigoroso?

O parâmetro response_format permite solicitar que o modelo retorne dados em um formato específico. Se você deseja usar "Saídas Estruturadas" (Structured Outputs), deve defini-lo como {"type": "json_schema"} e definir o seu JSON Schema internamente, ativando strict: true. Isso garante que o modelo gere conteúdo 100% de acordo com os campos e tipos de dados que você definiu, eliminando a necessidade de verificações adicionais de tolerância a falhas JSON no seu código.

2. Por que minha saída JSON foi truncada?

Se nos seus dados de resposta, o valor de choices[0].finish_reason for length, isso significa que o texto gerado atingiu o limite de max_tokens ou excedeu o limite máximo de comprimento de contexto do modelo. Recomenda-se aumentar o valor do parâmetro max_tokens na sua requisição.

3. Qual é a diferença entre os parâmetros temperature e top_p? Qual devo ajustar?

Ambos são parâmetros usados para controlar a aleatoriedade da saída do modelo:

• temperature redimensiona a distribuição de probabilidade da saída do modelo. Valores mais baixos tornam a saída mais rigorosa e determinística; valores mais altos a tornam mais divergente e criativa.
• top_p (Amostragem de Núcleo) restringe o modelo a escolher apenas entre os tokens mais frequentes cuja probabilidade cumulativa atinge p. Recomendação Oficial: Ajuste apenas um desses parâmetros, não modifique temperature e top_p ao mesmo tempo.

4. O que acontece ao ativar stream: true?

Quando stream: true é configurado, a API não esperará até que a resposta completa seja gerada para retornar. Em vez disso, ela transmitirá os fragmentos de dados em tempo real (streaming), como uma máquina de escrever. O formato de dados retornado será alterado para Server-Sent Events (SSE). O cliente precisará escutar o fluxo de dados para concatenar o delta.content até receber o marcador [DONE], o que indica o fim da transmissão.

5. Como posso garantir a mesma resposta exata sempre que chamar o mesmo Prompt?

Embora os grandes modelos de linguagem (LLMs) tenham uma natureza aleatória, você pode obter o máximo de determinismo na saída passando o parâmetro de semente (seen / Seed) específico e definindo a temperature como 0. Se você observar que o system_fingerprint no resultado retornado mudou, isso indica que a configuração do modelo de backend passou por ajustes finos; neste caso, mesmo que o Seed seja o mesmo, o resultado pode apresentar pequenas variações.