Texto

Criar Resposta

Cria uma resposta usando o formato da OpenAI Responses API

POST
/v1/responses

Use este endpoint quando o accepted_request_formats de um modelo incluir openai_responses. As requisições e respostas usam o formato da Responses API e não são convertidas: um modelo sem esse formato retorna 400 aqui, portanto use Chat Completions para ele. Campos opcionais e valores suportados dependem do modelo selecionado.

Corpo da Requisição

modelstringobrigatório

ID do modelo a ser utilizado. Consulte Modelos para obter as opções disponíveis.

inputstring | array

Entrada para a resposta. É opcional quando a requisição usa, em vez disso, um prompt reutilizável ou continua uma resposta armazenada com previous_response_id.

Cada item é um objeto com um type. Os tipos comuns são:

  • message: Uma mensagem de conversa com role e content
  • function_call: Uma requisição de chamada de função
  • function_call_output: Saída de uma chamada de função
  • reasoning: Um item de pensamento de uma resposta anterior. Envie-o de volta inalterado

Outros tipos de itens dependem do modelo selecionado.

Para entrada multimodal, message.content pode ser uma string simples ou um array de blocos de conteúdo. Para modelos com capacidade de processamento de imagem, passe as imagens como blocos input_image em vez de incorporar URLs ou strings Base64 diretamente no texto simples.

Exemplos de blocos de conteúdo:

  • { "type": "input_text", "text": "Describe this image" }
  • { "type": "input_image", "image_url": "https://example.com/image.jpg" }
  • { "type": "input_image", "image_url": "data:image/png;base64,..." }
instructionsstring

Instruções de sistema para o modelo (equivalente à mensagem de sistema).

max_output_tokensinteger

Número máximo de tokens a serem gerados.

temperaturenumber

Temperatura de amostragem. Os valores suportados e os padrões dependem do modelo selecionado.

toolsarray

Ferramentas que o modelo pode chamar. Os tipos e combinações suportados dependem do modelo selecionado.

streambooleanpadrão: false

Se for true, retorna uma stream de eventos. Consulte Streaming.

previous_response_idstring

ID de uma resposta anterior a partir da qual continuar a conversa. A resposta deve pertencer à sua conta e ainda estar armazenada; caso contrário, a requisição retornará 404 com o código response_not_found. Continue com o modelo que a produziu. Se o serviço que produziu a resposta estiver temporariamente indisponível, a requisição poderá retornar 503.

storebooleanpadrão: true

Indica se a resposta deve ser armazenada para recuperação posterior e para previous_response_id. Com false, o TokenLab não mantém a resposta, e GET /v1/responses/{id} não poderá retorná-la.

backgroundbooleanpadrão: false

Solicita execução assíncrona. O suporte depende do modelo selecionado. A chamada de criação retorna imediatamente, geralmente com o status queued ou in_progress. Faça polling em Recuperar uma resposta até que o status seja completed, incomplete, failed ou cancelled. Uma requisição em segundo plano pode retornar 503 enquanto o processamento em segundo plano estiver temporariamente indisponível.

tool_choicestring | object

Política de escolha de ferramentas, como auto, none, required ou um objeto que nomeia uma ferramenta. Os valores suportados dependem do modelo selecionado.

includearray

Seções de saída adicionais a serem retornadas, quando o modelo selecionado as suportar.

stream_optionsobject

Opções de streaming. include_obfuscation é encaminhado quando o modelo selecionado o suporta.

truncationstring

Estratégia de truncamento para conversas longas, quando o modelo selecionado a suportar.

service_tierstring

O TokenLab atende e fatura requisições de Responses no nível de serviço padrão. auto e default são aceitos. Outros valores, como flex ou priority, são removidos da requisição, e a requisição é cobrada pelo preço padrão.

promptobject

Referência a um modelo de prompt reutilizável e variáveis.

metadataobject

Metadados personalizados armazenados com a resposta.

textobject

Configurações de saída de texto. O suporte para text.format depende do modelo selecionado.

parallel_tool_callsboolean

Indica se chamadas de ferramentas múltiplas em paralelo são permitidas, quando suportado pelo modelo selecionado.

top_pnumber

Parâmetro de amostragem de núcleo (nucleus sampling) (0-1).

reasoningobject

Opções de raciocínio, incluindo effort, dependem do modelo selecionado.

Resposta

idstring

Identificador único para a resposta.

objectstring

Sempre response.

created_atinteger

Timestamp Unix de quando a resposta foi criada.

statusstring

Estado da resposta: queued, in_progress, completed, incomplete, failed ou cancelled. Verifique este campo mesmo quando a requisição HTTP for bem-sucedida.

outputarray

Lista de itens de saída gerados pelo modelo.

usageobject

Estatísticas de uso de tokens.

Endpoints Relacionados

  • GET /v1/responses/{id} recupera uma resposta armazenada.
  • DELETE /v1/responses/{id} exclui uma resposta armazenada. Não cancela a geração.
  • POST /v1/responses/compact compacta uma conversa e retorna um objeto response.compaction.
  • wss://api.tokenlab.sh/v1/responses cria respostas via WebSocket. Consulte Streaming.
  • Os endpoints de cancelamento, input-items e input-tokens não estão disponíveis no momento.

Requisição

cURL
curl -X POST "https://api.tokenlab.sh/v1/responses" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "input": [
      {"type": "message", "role": "user", "content": "Hello!"}
    ],
    "max_output_tokens": 1000
  }'
Python
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh/v1"
)

response = client.responses.create(
    model="gpt-5.6-terra",
    input=[
        {"type": "message", "role": "user", "content": "Hello!"}
    ],
    max_output_tokens=1000
)

print(response.output)
JavaScript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-api-key',
  baseURL: 'https://api.tokenlab.sh/v1'
});

const response = await client.responses.create({
  model: 'gpt-5.6-terra',
  input: [
    { type: 'message', role: 'user', content: 'Hello!' }
  ],
  max_output_tokens: 1000
});

console.log(response.output);
Go
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    payload := map[string]interface{}{
        "model": "gpt-5.6-terra",
        "input": []map[string]interface{}{
            {"type": "message", "role": "user", "content": "Hello!"},
        },
        "max_output_tokens": 1000,
    }
    body, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", "https://api.tokenlab.sh/v1/responses", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer sk-your-api-key")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result["output"])
}
PHP
<?php
$ch = curl_init('https://api.tokenlab.sh/v1/responses');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer sk-your-api-key'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'model' => 'gpt-5.6-terra',
        'input' => [
            ['type' => 'message', 'role' => 'user', 'content' => 'Hello!']
        ],
        'max_output_tokens' => 1000
    ])
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data['output']);

Exemplo de Entrada com Visão

Use modelos com capacidade de visão colocando imagens dentro de message.content como blocos input_image. O valor de image_url pode ser uma URL pública ou uma URL de dados Base64.

{
  "model": "gpt-5.6-terra",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Please describe this image."
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/demo.jpg"
        }
      ]
    }
  ]
}
{
  "model": "gpt-5.6-terra",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Please describe this image."
        },
        {
          "type": "input_image",
          "image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
        }
      ]
    }
  ]
}

Resposta

Response
{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1706000000,
  "status": "completed",
  "model": "gpt-5.6-terra",
  "output": [
    {
      "id": "msg_abc123",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {"type": "output_text", "text": "Hello! How can I help you today?", "annotations": []}
      ]
    }
  ],
  "usage": {
    "input_tokens": 10,
    "output_tokens": 12,
    "total_tokens": 22
  }
}

Erros

Os erros usam o objeto error no estilo OpenAI. Casos comuns: 400 para um campo inválido ou um modelo sem o formato Responses, 401 para uma chave inválida, 402 para saldo insuficiente, 404 para um previous_response_id desconhecido, 429 para o limite de taxa (rate limit) e 503 quando o modelo não puder atender à requisição no momento. Consulte Tratar erros da API.

Autorização

BearerAuth
AuthorizationBearer <token>

Autenticação por Chave de API. Crie ou gerencie chaves de API em Dashboard > API > API Keys.

Local: header

Cabeçalhos

X-TokenLab-Delivery-Policy?string

Política de entrega por solicitação. Substitui os padrões da API key e do Workspace. Tenta automaticamente o TokenLab Verified primeiro e pode alternar uma vez para Official apenas antes da saída, aceitação da solicitação ou criação de recurso persistente.

Valores permitidos

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Chave opcional que interrompe uma segunda execução da mesma requisição. Envie um novo valor único, como um UUID, para cada requisição e mantenha-o para novas tentativas após um timeout. Uma nova tentativa com a mesma chave não é executada novamente: ela retorna 409 com idempotency_replay_unavailable, ou geralmente idempotency_conflict quando o corpo foi alterado. Exceção: quando um resultado sem stream é concluído após o cliente se desconectar, uma nova tentativa com a mesma chave e corpo dentro de 24 horas retorna esse resultado (até 1 MB) com o cabeçalho Idempotent-Replayed: true e sem cobrança adicional. Uma chave com mais de 255 caracteres é ignorada e a requisição não terá proteção de idempotência. Com background: true, uma nova tentativa com a mesma chave e corpo retorna o objeto de resposta original e não cria ou cobra uma segunda resposta; um corpo diferente é rejeitado e seu código de status não é garantido. Veja Retry safely with an idempotency key.

Comprimento1 <= length <= 255

Corpo da requisição

application/json

Resposta

application/json

application/json

application/json

application/json

application/json