Responses API — Documentación de TokSpan

Endpoint

http
POST https://api.tokspan.com/v1/responses

Ejemplos Rápidos

La Responses API sigue los mismos patrones del SDK de OpenAI — solo cambia el nombre del método:

from openai import OpenAI

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

response = client.responses.create(
    model="MODEL_NAME",
    input="What is the capital of France?",
)

print(response.output_text)

shell
curl -X POST "https://api.tokspan.com/v1/responses" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "input": "What is the capital of France?"
  }'

json — Response
{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1700000000,
  "status": "completed",
  "model": "MODEL_NAME",
  "output": [{
    "type": "message",
    "role": "assistant",
    "content": [{
      "type": "output_text",
      "text": "The capital of France is Paris.",
      "annotations": []
    }]
  }],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 8,
    "total_tokens": 20
  }
}

Cuerpo de la Solicitud

Parámetro	Tipo	Requerido	Descripción
model	string	Sí	ID del modelo (ej., `gpt-4o`, `claude-opus-4-8`). Consulta Modelos para el catálogo completo.
input	string / array	Sí	La entrada para la respuesta. Puede ser una cadena simple o un array de elementos de mensaje (ej., `input_text`, `input_image`).
instructions	string	No	Instrucciones a nivel de sistema para el modelo — el equivalente en la Responses API de un mensaje <code>system</code>.
max_output_tokens	integer	No	Máximo de tokens a generar en la respuesta.
temperature	number	No	Temperatura de muestreo (0–2). Mayor = más aleatorio.
stream	boolean	No	Habilitar streaming SSE. Predeterminado: `false`.
tools	array	No	Herramientas que el modelo puede llamar, incluidas las herramientas integradas como `web_search_preview` y `file_search`.
tool_choice	string / object	No	Control de selección de herramienta: `"auto"`, `"none"`, `"required"`, o un objeto de herramienta específico.
previous_response_id	string	No	Pasa el `id` de la respuesta anterior para continuar una conversación multi-turno con estado.
reasoning	object	No	Configuración de razonamiento para modelos de razonamiento (ej., <code>effort</code>: <code>"low"</code> \| <code>"medium"</code> \| <code>"high"</code>).

Respuestas en Streaming (SSE)

Establece stream: true para recibir la respuesta de forma incremental mediante Server-Sent Events — igual que el streaming de Chat Completions.

shell
curl -X POST "https://api.tokspan.com/v1/responses" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "input": "Tell me a story.",
    "stream": true
  }'

Herramientas Integradas

La Responses API admite herramientas integradas que no requieren definiciones de funciones personalizadas:

Búsqueda Web

json
{
  "model": "MODEL_NAME",
  "input": "What is the latest news about AI?",
  "tools": [{
    "type": "web_search_preview"
  }]
}

Búsqueda de Archivos

json
{
  "model": "MODEL_NAME",
  "input": "Summarize the Q3 report",
  "tools": [{
    "type": "file_search",
    "vector_store_ids": ["vs_abc123"]
  }]
}

Disponibilidad de herramientas integradas: La búsqueda web y la búsqueda de archivos requieren modelos y canales upstream que las admitan. La disponibilidad depende de los canales configurados en tu backend.