Crear una finalización de chat

POST

chat

completions

import os
from openai import OpenAI
client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key=os.environ["COMETAPI_KEY"],
)

completion = client.chat.completions.create(
    model="gpt-5.6-sol",
    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"
}

{
  "error": {
    "code": "",
    "message": "model name is required (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "code": "",
    "message": "invalid token (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "message": "field messages is required (request id: <request_id>)",
    "type": "comet_api_error",
    "param": "",
    "code": "invalid_request"
  }
}

CometAPI enruta Chat Completions a varios proveedores, incluidos OpenAI, Claude y Gemini, mediante una única interfaz compatible con OpenAI. Cambie entre modelos modificando el parámetro model; la mayoría de los SDK compatibles con OpenAI funcionan configurando base_url en https://api.cometapi.com/v1.

Los parámetros de solicitud y los campos de respuesta pueden variar considerablemente entre proveedores de modelos. Consulte la documentación oficial del proveedor del modelo que utiliza siempre que necesite la lista completa de parámetros o comportamiento específico del proveedor. Por ejemplo, reasoning_effort solo se aplica a los modelos de razonamiento (o-series, GPT-5.1+), y algunos modelos no admiten logprobs ni n > 1.

Para los modelos OpenAI Pro, los modelos de razonamiento o-series y los modelos Codex, use el endpoint de Responses en su lugar. Estas familias de modelos tienen un soporte más completo en la API de Responses.

Roles de los mensajes

Rol	Descripción
`system`	Define el comportamiento y la personalidad del asistente. Se coloca al inicio de la conversación.
`developer`	Sustituye a `system` en los modelos más recientes (o1+). Proporciona instrucciones que el modelo debe seguir independientemente de la entrada del usuario.
`user`	Mensajes del usuario final.
`assistant`	Respuestas anteriores del modelo, utilizadas para mantener el historial de la conversación.
`tool`	Resultados de llamadas a herramientas o 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), prefiera developer en lugar de system para los mensajes de instrucciones. Ambos funcionan, pero developer ofrece un seguimiento de instrucciones más sólido.

Enviar entrada Multimodal

Muchos modelos admiten imágenes y audio junto con texto. Para enviar mensajes Multimodal, use el formato de matriz para content:

{
  "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 imágenes:

low — más rápido, usa menos tokens (costo fijo)
high — análisis detallado, consume más tokens
auto — el modelo decide (predeterminado)

Transmitir respuestas

Para recibir salida incremental, configure stream en true. La respuesta se entrega como Server-Sent Events (SSE), donde cada evento contiene un objeto chat.completion.chunk:

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, configure stream_options.include_usage en true. Los datos de uso aparecen en el fragmento final antes de [DONE].

Solicitar salida estructurada

Para forzar que el modelo devuelva JSON válido que coincida con un esquema específico, use 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
      }
    }
  }
}

{
  "response_format": {"type": "json_object"}
}

El modo JSON Schema (json_schema) garantiza que la salida coincida exactamente con su esquema. El modo JSON Object (json_object) solo garantiza JSON válido; la estructura no se aplica.

Llamar a herramientas y funciones

Para permitir que el modelo llame a funciones externas, proporcione 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 modelo decida llamar a una herramienta, la respuesta tendrá finish_reason: "tool_calls" y la matriz message.tool_calls contendrá el nombre y los argumentos de la función. Luego ejecute la función y envíe el resultado de vuelta como un mensaje tool con el tool_call_id correspondiente.

Notas entre proveedores

Compatibilidad de parámetros entre proveedores

Parámetro	OpenAI GPT	Claude (mediante compat)	Gemini (mediante compat)
`temperature`	0–2	0–1	0–2
`top_p`	0–1	0–1	0–1
`n`	1–128	solo 1	1–8
`stop`	Hasta 4	Hasta 4	Hasta 5
`tools`	✅	✅	✅
`response_format`	✅	✅ (json_schema)	✅
`logprobs`	✅	❌	❌
`reasoning_effort`	o-series, GPT-5.1+	❌	❌ (use `thinking` para Gemini nativo)

max_tokens frente a max_completion_tokens

max_tokens — El parámetro heredado. Funciona con la mayoría de los modelos, pero está obsoleto para los modelos OpenAI más recientes.
max_completion_tokens — El parámetro recomendado para los modelos GPT-4.1, de 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 la asignación al enrutar a diferentes proveedores.

rol system frente a developer

system — El rol de instrucciones tradicional. Funciona con todos los modelos.
developer — Introducido con los modelos o1. Proporciona un seguimiento de instrucciones más sólido para modelos recientes. Recurre al comportamiento de system en modelos anteriores.

Use developer para nuevos proyectos dirigidos a los modelos GPT-4.1+ o o-series.

Preguntas frecuentes

¿Cómo gestionar los límites de tasa?

Al encontrar 429 Too Many Requests, implemente una espera exponencial:

import os
import time
import random
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key=os.environ["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.6-sol",
                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?

Incluya el historial completo de la conversación en la matriz 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`?

Valor	Significado
`stop`	Finalización natural o se alcanzó una secuencia de parada.
`length`	Se alcanzó el límite de `max_tokens` o `max_completion_tokens`.
`tool_calls`	El modelo invocó una o más llamadas a herramientas o funciones.
`content_filter`	La salida se filtró debido a la política de contenido.

¿Cómo controlar los costos?

Use max_completion_tokens para limitar la longitud de salida.
Use gpt-5.6-terra para lograr un equilibrio entre inteligencia y costo, o gpt-5.6-luna para cargas de trabajo eficientes y de gran volumen.
Mantenga los prompts concisos; evite el contexto redundante.
Supervise el uso de tokens en el campo de respuesta usage.

Autorizaciones

Authorization

string

header

requerido

Bearer token authentication. Use your CometAPI key.

Cuerpo

application/json

model

string

predeterminado:gpt-5.6-sol

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).

Show child attributes

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

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.

Show child attributes

tools

object[]

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

Show child attributes

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.

Show child attributes

service_tier

enum<string>

Specifies the processing tier.

Opciones disponibles:

auto,

default,

flex,

priority

Respuesta

Successful chat completion response.

string

Unique completion identifier.

Ejemplo:

"chatcmpl-abc123"

object

enum<string>

Object type. Non-streaming responses use chat.completion.

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-2026-03-05"

choices

object[]

Array of completion choices.

Show child attributes

usage

object

Token accounting for this request. Billing uses these counts.

Show child attributes

service_tier

string

Service tier that processed the request, when the provider reports one.

Ejemplo:

"default"

system_fingerprint

string | null

Provider backend configuration fingerprint, when the provider reports one.

Ejemplo:

"fp_490a4ad033"

APIs de texto y chat

Crear una respuesta de modelo

import os
from openai import OpenAI
client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key=os.environ["COMETAPI_KEY"],
)

completion = client.chat.completions.create(
    model="gpt-5.6-sol",
    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"
}

{
  "error": {
    "code": "",
    "message": "model name is required (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "code": "",
    "message": "invalid token (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "message": "field messages is required (request id: <request_id>)",
    "type": "comet_api_error",
    "param": "",
    "code": "invalid_request"
  }
}

Moderación de contenido

Claves API

Roles de los mensajes

Enviar entrada Multimodal

Transmitir respuestas

Solicitar salida estructurada

Llamar a herramientas y funciones

Notas entre proveedores

Preguntas frecuentes

¿Cómo gestionar los límites de tasa?

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

¿Qué significa `finish_reason`?

¿Cómo controlar los costos?

Autorizaciones

Cuerpo

Respuesta

​Roles de los mensajes

​Enviar entrada Multimodal

​Transmitir respuestas

​Solicitar salida estructurada

​Llamar a herramientas y funciones

​Notas entre proveedores

​Preguntas frecuentes

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

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

​¿Qué significa finish_reason?

​¿Cómo controlar los costos?

Autorizaciones

Cuerpo

Respuesta

Roles de los mensajes

Enviar entrada Multimodal

Transmitir respuestas

Solicitar salida estructurada

Llamar a herramientas y funciones

Notas entre proveedores

Preguntas frecuentes

¿Cómo gestionar los límites de tasa?

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

¿Qué significa `finish_reason`?

¿Cómo controlar los costos?