Saltar al contenido principal
POST
/
v1
/
chat
/
completions
from openai import OpenAI
client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key="<COMETAPI_KEY>",
)

completion = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"},
    ],
)

print(completion.choices[0].message)
{
  "id": "chatcmpl-DNA27oKtBUL8TmbGpBM3B3zhWgYfZ",
  "object": "chat.completion",
  "created": 1774412483,
  "model": "gpt-4.1-nano-2025-04-14",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Four",
        "refusal": null,
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 29,
    "completion_tokens": 2,
    "total_tokens": 31,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "service_tier": "default",
  "system_fingerprint": "fp_490a4ad033"
}

​
Resumen

El endpoint de Chat Completions es la API más utilizada para interactuar con modelos de lenguaje de gran tamaño. Acepta una conversación compuesta por múltiples mensajes y devuelve la respuesta del modelo. CometAPI enruta este endpoint a múltiples proveedores —incluidos OpenAI, Anthropic Claude (mediante una capa de compatibilidad), Google Gemini y otros— a través de una única interfaz unificada. Puedes cambiar entre modelos simplemente modificando el parámetro model.
Este endpoint sigue el formato de OpenAI Chat Completions. La mayoría de los SDK y herramientas compatibles con OpenAI funcionan con CometAPI cambiando base_url a https://api.cometapi.com/v1.

​
Notas importantes

Comportamiento específico del modelo — Diferentes modelos pueden admitir distintos subconjuntos de parámetros y devolver campos de respuesta ligeramente diferentes. Por ejemplo, reasoning_effort solo se aplica a los modelos de razonamiento (o-series, GPT-5.1+), y algunos modelos pueden no admitir logprobs o n > 1.
Transferencia directa de la respuesta — CometAPI transmite las respuestas del modelo sin modificaciones (excepto la normalización del formato al enrutar entre proveedores), lo que garantiza que recibas una salida coherente con la API original.
Modelos OpenAI Pro — Para los modelos de la serie OpenAI Pro (p. ej., o1-pro), usa el endpoint responses en su lugar.

​
Roles de mensaje

RolDescripción
systemEstablece el comportamiento y la personalidad del asistente. Se coloca al inicio de la conversación.
developerSustituye a system en los modelos más recientes (o1+). Proporciona instrucciones que el modelo debe seguir independientemente de la entrada del usuario.
userMensajes del usuario final.
assistantRespuestas anteriores del modelo, usadas para mantener el historial de la conversación.
toolResultados de llamadas a herramientas/funciones. Debe incluir tool_call_id que coincida con la llamada a herramienta original.
Para los modelos más recientes (GPT-4.1, serie GPT-5, o-series), prefiere developer sobre system para los mensajes de instrucción. Ambos funcionan, pero developer ofrece un seguimiento de instrucciones más sólido.

​
Entrada Multimodal

Muchos modelos admiten imágenes y audio junto con texto. Usa el formato de arreglo para content para enviar mensajes multimodales: 
{
  "role": "user",
  "content": [
    {"type": "text", "text": "Describe this image"},
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/image.png",
        "detail": "high"
      }
    }
  ]
}
El parámetro detail controla la profundidad del análisis de la imagen:
  • low — más rápido, usa menos tokens (costo fijo)
  • high — análisis detallado, consume más tokens
  • auto — el modelo decide (predeterminado)

​
Streaming

Cuando stream se establece en true, la respuesta se entrega como Server-Sent Events (SSE). Cada evento contiene un objeto chat.completion.chunk con contenido incremental: 
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

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

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

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

data: [DONE]
Para incluir estadísticas de uso de tokens en las respuestas de Streaming, establece stream_options.include_usage en true. Los datos de uso aparecen en el fragmento final antes de [DONE].

​
Structured Outputs

Fuerza al model a devolver JSON válido que coincida con un esquema específico usando response_format: 
{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "result",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "answer": {"type": "string"},
          "confidence": {"type": "number"}
        },
        "required": ["answer", "confidence"],
        "additionalProperties": false
      }
    }
  }
}
El modo JSON Schema (json_schema) garantiza que la salida coincida exactamente con tu esquema. El modo JSON Object (json_object) solo garantiza JSON válido; la estructura no se aplica.

​
Tool / Function Calling

Habilita al model para llamar funciones externas proporcionando definiciones de herramientas: 
{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "City name"}
          },
          "required": ["location"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}
Cuando el model decide llamar una herramienta, la respuesta tendrá finish_reason: "tool_calls" y el arreglo message.tool_calls contendrá el nombre de la función y los argumentos. Luego ejecutas la función y envías el resultado de vuelta como un mensaje tool con el tool_call_id correspondiente.

​
Campos de respuesta

FieldDescription
idIdentificador único de completion (p. ej. chatcmpl-abc123).
objectSiempre chat.completion.
modelEl model que generó la respuesta (puede incluir un sufijo de versión).
choicesArreglo de opciones de completion (normalmente 1, a menos que n > 1).
choices[].messageEl mensaje de respuesta del assistant con role, content y, opcionalmente, tool_calls.
choices[].finish_reasonPor qué el model se detuvo: stop, length, tool_calls o content_filter.
usageDesglose del consumo de tokens: prompt_tokens, completion_tokens, total_tokens y subcuentas detalladas.
system_fingerprintHuella digital de la configuración del backend para depurar la reproducibilidad.

​
Notas entre proveedores

ParameterOpenAI GPTClaude (via compat)Gemini (via compat)
temperature0–20–10–2
top_p0–10–10–1
n1–128Solo 11–8
stopHasta 4Hasta 4Hasta 5
tools✅✅✅
response_format✅✅ (json_schema)✅
logprobs✅❌❌
reasoning_efforto-series, GPT-5.1+❌❌ (usar thinking para Gemini native)
  • max_tokens — El parámetro heredado. Funciona con la mayoría de los modelos, pero está obsoleto para los modelos más nuevos de OpenAI.
  • max_completion_tokens — El parámetro recomendado para los modelos GPT-4.1, la serie GPT-5 y o-series. Es obligatorio para los modelos de razonamiento, ya que incluye tanto los tokens de salida como los tokens de razonamiento.
CometAPI gestiona automáticamente el mapeo al enrutar hacia distintos proveedores.
  • system — El rol de instrucción tradicional. Funciona con todos los modelos.
  • developer — Introducido con los modelos o1. Proporciona un seguimiento de instrucciones más sólido para los modelos más nuevos. En los modelos más antiguos, se comporta como system.
Usa developer para proyectos nuevos dirigidos a modelos GPT-4.1+ u o-series.

​
Preguntas frecuentes

​
¿Cómo manejar los límites de tasa?

Cuando encuentres 429 Too Many Requests, implementa backoff exponencial: 
import time
import random
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key="<COMETAPI_KEY>",
)

def chat_with_retry(messages, max_retries=3):
    for i in range(max_retries):
        try:
            return client.chat.completions.create(
                model="gpt-5.4",
                messages=messages,
            )
        except RateLimitError:
            if i < max_retries - 1:
                wait_time = (2 ** i) + random.random()
                time.sleep(wait_time)
            else:
                raise

​
¿Cómo mantener el contexto de la conversación?

Incluye el historial completo de la conversación en el array messages: 
messages = [
    {"role": "developer", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is Python?"},
    {"role": "assistant", "content": "Python is a high-level programming language..."},
    {"role": "user", "content": "What are its main advantages?"},
]

​
¿Qué significa finish_reason?

ValueMeaning
stopFinalización natural o se alcanzó una secuencia de parada.
lengthSe alcanzó el límite de max_tokens o max_completion_tokens.
tool_callsEl modelo invocó una o más llamadas a herramientas/funciones.
content_filterLa salida fue filtrada debido a la política de contenido.

​
¿Cómo controlar los costos?

  1. Usa max_completion_tokens para limitar la longitud de la salida.
  2. Elige modelos rentables (p. ej., gpt-5.4-mini o gpt-5.4-nano para tareas más simples).
  3. Mantén los prompts concisos — evita contexto redundante.
  4. Supervisa el uso de tokens en el campo usage de la respuesta.

Autorizaciones

​
Authorization
string
header
requerido

Bearer token authentication. Use your CometAPI key.

Cuerpo

application/json
​
model
string
predeterminado:gpt-5.4
requerido

Model ID to use for this request. See the Models page for current options.

Ejemplo:

"gpt-4.1"

​
messages
object[]
requerido

A list of messages forming the conversation. Each message has a role (system, user, assistant, or developer) and content (text string or multimodal content array).

​
stream
boolean

If true, partial response tokens are delivered incrementally via server-sent events (SSE). The stream ends with a data: [DONE] message.

​
temperature
number
predeterminado:1

Sampling temperature between 0 and 2. Higher values (e.g., 0.8) produce more random output; lower values (e.g., 0.2) make output more focused and deterministic. Recommended to adjust this or top_p, but not both.

Rango requerido: 0 <= x <= 2
​
top_p
number
predeterminado:1

Nucleus sampling parameter. The model considers only the tokens whose cumulative probability reaches top_p. For example, 0.1 means only the top 10% probability tokens are considered. Recommended to adjust this or temperature, but not both.

Rango requerido: 0 <= x <= 1
​
n
integer
predeterminado:1

Number of completion choices to generate for each input message. Defaults to 1.

​
stop
string

Up to 4 sequences where the API will stop generating further tokens. Can be a string or an array of strings.

​
max_tokens
integer

Maximum number of tokens to generate in the completion. The total of input + output tokens is capped by the model's context length.

​
presence_penalty
number
predeterminado:0

Number between -2.0 and 2.0. Positive values penalize tokens based on whether they have already appeared, encouraging the model to explore new topics.

Rango requerido: -2 <= x <= 2
​
frequency_penalty
number
predeterminado:0

Number between -2.0 and 2.0. Positive values penalize tokens proportionally to how often they have appeared, reducing verbatim repetition.

Rango requerido: -2 <= x <= 2
​
logit_bias
object

A JSON object mapping token IDs to bias values from -100 to 100. The bias is added to the model's logits before sampling. Values between -1 and 1 subtly adjust likelihood; -100 or 100 effectively ban or force selection of a token.

​
user
string

A unique identifier for your end-user. Helps with abuse detection and monitoring.

​
max_completion_tokens
integer

An upper bound for the number of tokens to generate, including visible output tokens and reasoning tokens. Use this instead of max_tokens for GPT-4.1+, GPT-5 series, and o-series models.

​
response_format
object

Specifies the output format. Use {"type": "json_object"} for JSON mode, or {"type": "json_schema", "json_schema": {...}} for strict structured output.

​
tools
object[]

A list of tools the model may call. Currently supports function type tools.

​
tool_choice
predeterminado:auto

Controls how the model selects tools. auto (default): model decides. none: no tools. required: must call a tool.

​
logprobs
boolean
predeterminado:false

Whether to return log probabilities of the output tokens.

​
top_logprobs
integer

Number of most likely tokens to return at each position (0-20). Requires logprobs to be true.

Rango requerido: 0 <= x <= 20
​
reasoning_effort
enum<string>

Controls the reasoning effort for o-series and GPT-5.1+ models.

Opciones disponibles:
low,
medium,
high
​
stream_options
object

Options for streaming. Only valid when stream is true.

​
service_tier
enum<string>

Specifies the processing tier.

Opciones disponibles:
auto,
default,
flex,
priority

Respuesta

200 - application/json

Successful chat completion response.

​
id
string

Unique completion identifier.

Ejemplo:

"chatcmpl-abc123"

​
object
enum<string>
Opciones disponibles:
chat.completion
Ejemplo:

"chat.completion"

​
created
integer

Unix timestamp of creation.

Ejemplo:

1774412483

​
model
string

The model used (may include version suffix).

Ejemplo:

"gpt-5.4-2025-07-16"

​
choices
object[]

Array of completion choices.

​
usage
object
​
service_tier
string
Ejemplo:

"default"

​
system_fingerprint
string | null
Ejemplo:

"fp_490a4ad033"