Texto

Crear respuesta

Crea una respuesta utilizando el formato de Responses API de OpenAI

POST
/v1/responses

Utilice este endpoint cuando el accepted_request_formats de un modelo incluya openai_responses. Las solicitudes y respuestas utilizan el formato de Responses API y no se convierten: un modelo sin ese formato devuelve 400 aquí, por lo que debe utilizar Chat Completions para él. Los campos opcionales y los valores admitidos dependen del modelo seleccionado.

Cuerpo de la solicitud

modelstringobligatorio

ID del modelo a utilizar. Consulte Modelos para conocer las opciones disponibles.

inputstring | array

Entrada para la respuesta. Es opcional cuando la solicitud utiliza en su lugar un prompt reutilizable o continúa una respuesta almacenada con previous_response_id.

Cada elemento es un objeto con un type. Los tipos comunes son:

  • message: Un mensaje de conversación con rol y contenido
  • function_call: Una solicitud de llamada a función
  • function_call_output: Salida de una llamada a función
  • reasoning: Un elemento de razonamiento de una respuesta anterior. Envíelo de vuelta sin cambios

Otros tipos de elementos dependen del modelo seleccionado.

Para entradas multimodales, message.content puede ser una cadena de texto simple o un array de bloques de contenido. Para modelos con capacidad para imágenes, pase las imágenes como bloques input_image en lugar de incrustar URLs o cadenas Base64 directamente en texto sin formato.

Ejemplos de bloques de contenido:

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

Instrucciones del sistema para el modelo (equivalente al mensaje del sistema).

max_output_tokensinteger

Número máximo de tokens a generar.

temperaturenumber

Temperatura de muestreo. Los valores admitidos y los predeterminados dependen del modelo seleccionado.

toolsarray

Herramientas que el modelo puede llamar. Los tipos y combinaciones admitidos dependen del modelo seleccionado.

streambooleanpredeterminado: false

Si es true, devuelve un stream de eventos. Consulte Streaming.

previous_response_idstring

ID de una respuesta anterior desde la cual continuar la conversación. La respuesta debe pertenecer a su cuenta y seguir almacenada; de lo contrario, la solicitud devuelve 404 con el código response_not_found. Continúe con el modelo que la produjo. Si el servicio que generó la respuesta no está disponible temporalmente, la solicitud puede devolver 503.

storebooleanpredeterminado: true

Indica si se debe almacenar la respuesta para su posterior recuperación y para previous_response_id. Con false, TokenLab no conserva la respuesta y GET /v1/responses/{id} no podrá devolverla.

backgroundbooleanpredeterminado: false

Solicita la ejecución asíncrona. La compatibilidad depende del modelo seleccionado. La llamada de creación responde inmediatamente, por lo general con el status queued o in_progress. Realice sondeos en Recuperar una respuesta hasta que status sea completed, incomplete, failed o cancelled. Una solicitud en segundo plano puede devolver 503 mientras el procesamiento en segundo plano no esté disponible temporalmente.

tool_choicestring | object

Política de selección de herramientas, como auto, none, required o un objeto que especifique una herramienta. Los valores admitidos dependen del modelo seleccionado.

includearray

Secciones de salida adicionales a devolver, cuando el modelo seleccionado las admita.

stream_optionsobject

Opciones de streaming. include_obfuscation se reenvía cuando el modelo seleccionado lo admite.

truncationstring

Estrategia de truncamiento para conversaciones largas, cuando el modelo seleccionado la admita.

service_tierstring

TokenLab atiende y factura las solicitudes de Responses en el nivel de servicio estándar. Se aceptan auto y default. Otros valores, como flex o priority, se eliminan de la solicitud y esta se factura al precio estándar.

promptobject

Referencia a una plantilla de prompt reutilizable y variables.

metadataobject

Metadatos personalizados almacenados con la respuesta.

textobject

Configuración de la salida de texto. La compatibilidad con text.format depende del modelo seleccionado.

parallel_tool_callsboolean

Indica si se permiten múltiples llamadas a herramientas en paralelo, cuando el modelo seleccionado lo admita.

top_pnumber

Parámetro de muestreo de núcleo (0-1).

reasoningobject

Las opciones de razonamiento, incluido effort, dependen del modelo seleccionado.

Respuesta

idstring

Identificador único para la respuesta.

objectstring

Siempre response.

created_atinteger

Marca de tiempo Unix de cuándo se creó la respuesta.

statusstring

Estado de la respuesta: queued, in_progress, completed, incomplete, failed o cancelled. Compruebe este campo incluso cuando la solicitud HTTP tenga éxito.

outputarray

Lista de elementos de salida generados por el modelo.

usageobject

Estadísticas de uso de tokens.

Endpoints relacionados

  • GET /v1/responses/{id} recupera una respuesta almacenada.
  • DELETE /v1/responses/{id} elimina una respuesta almacenada. No cancela la generación.
  • POST /v1/responses/compact compacta una conversación y devuelve un objeto response.compaction.
  • wss://api.tokenlab.sh/v1/responses crea respuestas a través de WebSocket. Consulte Streaming.
  • Los endpoints cancel, input-items e input-tokens no están disponibles actualmente.

Solicitud

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']);

Ejemplo de entrada de visión

Utilice modelos con capacidad para imágenes colocando imágenes dentro de message.content como bloques input_image. El valor de image_url puede ser una URL pública o una URL de datos 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..."
        }
      ]
    }
  ]
}

Respuesta

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

Errores

Los errores utilizan el objeto error al estilo de OpenAI. Casos comunes: 400 para un campo no válido o un modelo sin el formato Responses, 401 para una clave no válida, 402 por saldo insuficiente, 404 para un previous_response_id desconocido, 429 para el límite de velocidad (rate limit) y 503 cuando el modelo no puede atender la solicitud en este momento. Consulte Manejo de errores de API.

Autorización

BearerAuth
AuthorizationBearer <token>

Autenticación con API Key. Cree o gestione API keys en Dashboard > API > API Keys.

Ubicación: header

Encabezados

X-TokenLab-Delivery-Policy?string

Política de entrega por solicitud. Sustituye los valores predeterminados de la API key y del Workspace. Auto intenta primero con TokenLab Verified y puede cambiar una vez a Official solo antes de la salida, la aceptación de la solicitud o la creación de recursos persistentes.

Valores permitidos

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

Clave opcional que detiene una segunda ejecución de la misma solicitud. Envíe un nuevo valor único, como un UUID, para cada solicitud y consérvelo para reintentos tras un tiempo de espera. Un reintento con la misma clave no se ejecuta de nuevo: devuelve 409 con idempotency_replay_unavailable, o generalmente idempotency_conflict cuando el cuerpo ha cambiado. Excepción: cuando un resultado sin streaming finaliza después de que el cliente se desconectara, un reintento con la misma clave y cuerpo dentro de las 24 horas devuelve ese resultado (hasta 1 MB) con el encabezado Idempotent-Replayed: true y sin un segundo cargo. Una clave de más de 255 caracteres se ignora y la solicitud no tendrá protección de idempotencia. Con background: true, un reintento con la misma clave y cuerpo devuelve el objeto de respuesta original en su lugar y no crea ni cobra una segunda respuesta; un cuerpo diferente será rechazado y su código de estado no está garantizado. Consulte Retry safely with an idempotency key.

Longitud1 <= length <= 255

Cuerpo de la solicitud

application/json

Respuesta

application/json

application/json

application/json

application/json

application/json