Criar Conclusão de Chat (Stream / Fluxo)

Referência da Documentação Oficial: OpenAI Chat Create

Descrição da Interface

Dado um prompt, o modelo retornará uma ou mais opções de conclusão de diálogo previstas. Esta interface suporta tanto o retorno padrão quanto o retorno em fluxo contínuo (Streaming / SSE), e pode retornar a probabilidade de tokens alternativos em cada posição.

Especificações da Requisição

• Método da Requisição: POST
• URL da Requisição: https://api.codingplanx.ai/v1/chat/completions

Cabeçalhos (Headers)

Corpo da Requisição (Request Body)

Exemplo de Requisição

{
  "model": "gpt-5-mini",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "你好"
    }
  ],
  "temperature": 1.0,
  "stream": true,
  "stream_options": {
    "include_usage": true
  }
}

---

Especificações da Resposta

• Content-Type: application/json (Não-streaming) ou text/event-stream (Em streaming quando stream: true)

Parâmetros da Resposta (Estrutura Não-Streaming)

Exemplo de Resposta (Não-Streaming / Resultado Agregado de Streaming)

{
    "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
    }
}

(Nota: Se stream: true for especificado na requisição, o corpo da resposta será um fluxo de eventos SSE separados por quebras de linha, cada linha começando com data: {...} e terminando com data: [DONE].)

---

FAQs (Perguntas Frequentes)

Q1: Como fazer o parse da resposta em fluxo quando stream: true está ativado? R: Quando stream: true está ativado, a API retorna dados através do protocolo Server-Sent Events (SSE). O cliente precisa ler o fluxo de resposta linha por linha, procurar por strings com o prefixo data: e fazer o parse para JSON. Note que a última mensagem do fluxo de dados é sempre data: [DONE], marcando o fim do fluxo. Este marcador de fim deve ser filtrado durante o parse.

Q2: Por que minha requisição trava ou retorna um fluxo de espaços em branco infinito após definir response_format como JSON? R: Quando você usa { "type": "json_object" } para ativar o modo JSON, é obrigatório instruir claramente o modelo ("por favor, gere no formato JSON") nas messages enviadas (geralmente no system prompt). Sem instruções de texto relevantes, o modelo pode ficar travado e gerar caracteres em branco infinitamente até atingir o limite de max_tokens.

Q3: Posso ajustar os parâmetros temperature e top_p simultaneamente? R: A documentação oficial recomenda fortemente não ajustar ambos simultaneamente. Ambos são mecanismos para controlar a aleatoriedade da saída do modelo. Se você deseja uma saída mais estável e previsível, diminua a temperature ou reduza o top_p; se deseja respostas mais criativas, aumente um deles. Alterar ambos ao mesmo tempo tornará os resultados difíceis de prever.

Q4: Para que serve o parâmetro extra_body.enable_thinking? R: Este é um parâmetro de extensão especial desta interface. Ao passar {"enable_thinking": true}, se o modelo sendo utilizado no backend suportar "Modo de Raciocínio (Thinking Mode / CoT)" (como alguns modelos grandes otimizados para raciocínio), o modelo ativará um processo de raciocínio profundo. Se o modelo não suportar, este parâmetro será geralmente ignorado.

Q5: Por que o finish_reason na resposta é length em vez de stop? R: Quando o finish_reason retorna length, isso indica que o modelo foi forçado a parar antes de gerar uma resposta completa. Isso geralmente ocorre porque o seu parâmetro max_tokens está configurado com um valor muito baixo, ou porque a soma de tokens do input e os tokens gerados excedeu o limite máximo da janela de contexto permitida pelo modelo atual. Tente aumentar o valor de max_tokens.