Chat Completions

Endpoint

POST https://api.tokspan.com/v1/chat/completions

Ejemplos Rápidos

La misma API, para todos los modelos. Elija su lenguaje:

from openai import OpenAI
client = OpenAI(api_key="sk-your-key", base_url="https://api.tokspan.com/v1")
response = client.chat.completions.create(model="gpt-4o", messages=[{"role":"user","content":"Hello"}])
print(response.choices[0].message.content)

import OpenAI from 'openai';
const client = new OpenAI({ apiKey: process.env.TOKSPAN_API_KEY, baseURL: 'https://api.tokspan.com/v1' });
const response = await client.chat.completions.create({ model: 'gpt-4o', messages: [{ role: 'user', content: 'Hello' }] });
console.log(response.choices[0].message.content);

curl -X POST "https://api.tokspan.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

Cuerpo de la Solicitud

Ejemplo de Solicitud y Respuesta

{
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "What is the capital of France?" }
  ],
  "temperature": 0.7,
  "max_tokens": 256
}

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "gpt-4o",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "The capital of France is Paris."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 8,
    "total_tokens": 33
  }
}

Campos de la Respuesta

Comprendiendo el Uso de Tokens

El objeto usage reporta los tokens consumidos para facturación:

• prompt_tokens — Tokens en sus mensajes de entrada (incluyendo el prompt de sistema, el historial y cualquier medio adjunto convertido a equivalentes de token)
• completion_tokens — Tokens generados por el modelo en la respuesta
• total_tokens — Suma de tokens de prompt + completación = lo que se le factura

Para entradas multimodales (imágenes, audio), los proveedores convierten los medios a equivalentes de token. GPT-4o cuenta ~85 tokens para una imagen de baja resolución y ~170+ para alta resolución. Su panel muestra el conteo final de tokens y el costo por solicitud.

Respuestas en Streaming (SSE)

Establezca stream: true para recibir tokens en tiempo real a medida que el modelo los genera. TokSpan utiliza Server-Sent Events (SSE) estándar — totalmente compatible con el formato de streaming de OpenAI.

Ejemplo

from openai import OpenAI

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

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Tell me a story."}],
    stream=True,
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

curl -X POST "https://api.tokspan.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Tell me a story."}],
    "stream": true
  }'

Formato de Fragmento SSE

Cada fragmento es un objeto JSON con el prefijo data:. El stream termina con data: [DONE]:

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},"index":0}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":" world"},"index":0}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{},"finish_reason":"stop","index":0}]}

data: [DONE]

Cada fragmento contiene un objeto delta (no message). El campo content puede estar vacío o ausente en el último fragmento. El último fragmento tiene finish_reason establecido y un delta vacío.

Streaming con Llamadas a Herramientas

Cuando el modelo llama a una función durante el streaming, los fragmentos de llamada a herramienta llegan en el delta con tool_calls — el nombre de la función y los argumentos se transmiten incrementalmente. Acumule todos los fragmentos para un tool_call_id dado para ensamblar la llamada a función completa, luego envíe de vuelta un mensaje con role: "tool".

Llamada a Herramientas / Funciones

TokSpan admite function calling compatible con OpenAI en todos los modelos capaces. Defina sus herramientas en la solicitud y los modelos responden con llamadas a función en JSON estructurado que su código ejecuta.

Definiendo Herramientas

Pase un array tools con definiciones de funciones. Cada función necesita un name, description y parameters en JSON Schema:

"tools": [{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get current weather for a city",
    "parameters": {
      "type": "object",
      "properties": {
        "city": { "type": "string" }
      },
      "required": ["city"]
    }
  }
}]

Respuesta del Modelo con Llamadas a Herramientas

Cuando el modelo decide llamar a una función, la respuesta incluye tool_calls en lugar de contenido de texto:

{
  "role": "assistant",
  "tool_calls": [{
    "id": "call_abc123",
    "type": "function",
    "function": {
      "name": "get_weather",
      "arguments": "{\"city\": \"Paris\"}"
    }
  }]
}

Flujo Completo de Llamada a Herramientas

1. Envíe la solicitud con definiciones de tools
2. Reciba tool_calls en la respuesta — extraiga el nombre de la función y los argumentos
3. Ejecute la función en su código (llame a su API de clima, consulte su base de datos, etc.)
4. Envíe los resultados de vuelta como un mensaje con role: "tool", referenciando el tool_call_id
5. El modelo responde con una respuesta en lenguaje natural incorporando los resultados de la herramienta

Modelos Compatibles

Tool calling es compatible con: GPT-4o, GPT-4.1, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 2.5 Pro, Gemini 2.5 Flash, DeepSeek V3, Mistral Large 3, Llama 4, Qwen3 y más. Consulte la página de Modelos para detalles de capacidad por modelo.

Vision / Entrada de Imágenes

Para modelos multimodales como GPT-4o y Claude 4 Vision, incluya imágenes como URLs o datos codificados en base64 en el array content:

{
  "model": "gpt-4o",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "What's in this image?" },
      { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
    ]
  }]
}

Formatos de imagen compatibles: PNG, JPEG, WebP, GIF (no animado). El tamaño máximo de imagen varía según el modelo — típicamente 20MB por imagen. Para modelos Claude, los documentos PDF también son compatibles como entrada visual.

Modo JSON / Salida Estructurada

Fuerce al modelo a devolver JSON válido configurando response_format:

• Modo JSON: {"type": "json_object"} — El modelo devuelve JSON válido. Debe incluir la palabra "JSON" en su prompt de sistema.
• Salida Estructurada: {"type": "json_schema", "json_schema": {...}} — El modelo devuelve JSON que coincide con su esquema exacto. Compatible con GPT-4o y modelos más recientes.