Chat de texto

POST /v1/chat/completions

Chama um modelo de texto. Ao contrário da imagem e do vídeo, este endpoint é síncrono: uma ida e volta e tens a resposta, sem sondagem. Pedido e resposta seguem o chat/completions da OpenAI, streaming incluído, por isso qualquer SDK da OpenAI funciona trocando o URL base.

Parâmetros

Parâmetro	Tipo	Descrição
model	string	Obrigatório. id de modelo de /v1/models com type text
messages	object[]	Obrigatório. Cada item {role, content}; role é system, user ou assistant. No máximo 64 por pedido
stream	boolean	Opcional. true passa a deltas por SSE; predefinição false devolve tudo de uma vez
temperature	number	Opcional. Passado tal e qual ao modelo
top_p	number	Opcional. Passado tal e qual
max_tokens	integer	Opcional. Passado tal e qual
stop	string\|string[]	Opcional. Passado tal e qual
presence_penalty / frequency_penalty	number	Opcional. Passado tal e qual

model é obrigatório e não tem predefinição: os modelos de texto diferem muito em tom, extensão e preço, pelo que escolher um em silêncio seria tomar por ti uma decisão que nunca viste.

Pedido

bash

curl https://open.pikpikgo.com/v1/chat/completions \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-fast-1",
    "messages": [
      { "role": "system", "content": "És argumentista especializado em curtas dramáticas." },
      { "role": "user", "content": "Dá-me a abertura de uma curta de mistério urbano, em três frases no máximo." }
    ]
  }'

Resposta

json

{
  "id": "chatcmpl-2608102214300000123456",
  "object": "chat.completion",
  "created": 1786372470,
  "model": "text-fast-1",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "À meia-noite o elevador para no 13.º andar. O prédio só tem doze." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 38, "completion_tokens": 126, "total_tokens": 164 },
  "credits": 4
}

Campo	Descrição
choices[0].message.content	O texto da resposta
choices[0].finish_reason	stop para fim normal, length quando atingiu max_tokens
usage	Contagem de tokens. O texto é faturado por token, por isso é esta a base do débito
credits	Créditos efetivamente debitados (não é um campo da OpenAI)

O texto é faturado por token, não por chamada: créditos = tokens de entrada × preço de entrada + tokens de saída × preço de saída, arredondado para cima e com um mínimo de 1 por chamada. Os preços são indicados por milhão de tokens na página de tarifas.

Resposta em streaming

Com stream: true a resposta passa a text/event-stream e chega em fotogramas chat.completion.chunk: o primeiro declara o role, o conteúdo vem delta a delta, depois um fotograma com finish_reason e por fim um com choices vazio mais usage e credits, fechado por data: [DONE].

bash

curl -N https://open.pikpikgo.com/v1/chat/completions \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-fast-1",
    "messages": [
      { "role": "user", "content": "Dá-me a abertura de uma curta de mistério urbano, em três frases no máximo." }
    ],
    "stream": true
  }'

text

data: {"id":"chatcmpl-2608102214300000123456","object":"chat.completion.chunk","created":1786372470,"model":"text-fast-1","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-2608102214300000123456","object":"chat.completion.chunk","created":1786372470,"model":"text-fast-1","choices":[{"index":0,"delta":{"content":"À meia"},"finish_reason":null}]}

data: {"id":"chatcmpl-2608102214300000123456","object":"chat.completion.chunk","created":1786372470,"model":"text-fast-1","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-2608102214300000123456","object":"chat.completion.chunk","created":1786372470,"model":"text-fast-1","choices":[],"usage":{"prompt_tokens":38,"completion_tokens":126,"total_tokens":164},"credits":4}

data: [DONE]

Com o SDK oficial da OpenAI não precisas de analisar o SSE à mão:

javascript

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.PIKPIK_API_KEY,
  baseURL: 'https://open.pikpikgo.com/v1',
})

// Streaming: deltas fotograma a fotograma; o último traz usage e os créditos
const stream = await client.chat.completions.create({
  model: 'text-fast-1',
  messages: [{ role: 'user', content: 'Dá-me a abertura de uma curta de mistério urbano, em três frases no máximo.' }],
  stream: true,
})

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '')
}

Em streaming, o débito baseia-se no usage do último fotograma; se o modelo a montante não o devolver, cobra-se o mínimo de 1 crédito. Além disso, a partir do momento em que os fotogramas começam a fluir o estado HTTP já é 200: uma falha a meio não pode tornar-se 4xx/5xx. Chega como um fotograma {"error": {...}} dentro do stream, seguido do habitual [DONE]; prevê esse caso na leitura.