Documentación para desarrolladores

Inferencia de IA

Inicio rápido

Obtén tu primera respuesta en unas pocas líneas. La API de inferencia es compatible con OpenAI, así que puedes apuntar cualquier SDK de OpenAI a la URL base de abajo y autenticarte con tu clave de API.

URL base
https://api.nebux.cloud/v1

Instalación

index.ts
npm install openai
index.ts
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "your-api-key",
  baseURL: "https://api.nebux.cloud/v1",
});

const completion = await client.chat.completions.create({
  model: "qwen3-14b",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Recommend me a book" },
    { role: "assistant", content: "Try The Shadow of the Wind" },
    { role: "user", content: "And a similar one?" },
  ],
});

console.log(completion.choices[0].message.content);
RESPUESTA
{
  "id": "chatcmpl-8f3a2b1c9d",
  "object": "chat.completion",
  "created": 1719763200,
  "model": "qwen3-14b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "If you liked it, try Nada, by Carmen Laforet."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 47,
    "completion_tokens": 13,
    "total_tokens": 60
  }
}

Autenticación

Todas las peticiones deben incluir tu clave de API en la cabecera Authorization como token Bearer.

Genera y gestiona tus claves de API desde el panel. Gestionar claves de API

Mantén tu clave de API en secreto. Nunca la expongas en código del lado del cliente ni la subas al control de versiones.

Header
Authorization: Bearer your-api-key

Chat completions

Genera una respuesta del modelo para una conversación. Envía una lista de mensajes y recibe la respuesta del asistente.

Parámetros

modelstringobligatorio

ID del modelo a usar.

messagesarrayobligatorio

La conversación hasta el momento, como una lista de mensajes.

rolestring

El rol del autor del mensaje.

systemDefine el comportamiento y el contexto del asistente.
userUn mensaje del usuario final.
assistantUna respuesta anterior del modelo.
toolEl resultado de una llamada a una herramienta, devuelto al modelo.
contentstring

El contenido de texto del mensaje.

namestring

Un nombre opcional para distinguir participantes con el mismo rol.

temperaturenumberopcional

Temperatura de muestreo entre 0 y 2. Valores más altos hacen la salida más aleatoria; valores más bajos, más enfocada y determinista.

top_pnumberopcional

Muestreo por núcleo: considera solo los tokens que forman la masa de probabilidad top_p. Usa este parámetro o temperature, no ambos.

max_tokensnumberopcional

El número máximo de tokens a generar en la respuesta.

stopstring | arrayopcional

Hasta cuatro secuencias en las que se detiene la generación. La secuencia de parada no se incluye en la salida.

frequency_penaltynumberopcional

Entre -2 y 2. Valores positivos penalizan los tokens según cuántas veces ya han aparecido, reduciendo la repetición.

presence_penaltynumberopcional

Entre -2 y 2. Valores positivos penalizan los tokens que ya han aparecido, animando al modelo a introducir nuevos temas.

seednumberopcional

Si se define, el modelo muestrea de forma lo más determinista posible para que peticiones repetidas con los mismos parámetros devuelvan resultados similares.

nnumberopcional

Cuántas respuestas generar por petición.

streambooleanopcional

Transmite la respuesta como Server-Sent Events. Consulta Streaming.

response_formatobjectopcional

Restringe el formato de salida, p. ej. a JSON. Consulta Modo JSON.

toolsarrayopcional

Una lista de funciones que el modelo puede invocar. Consulta Herramientas.

chat_template_kwargsobjectopcional

Activa el razonamiento en esta petición. Consulta Razonamiento.

index.ts
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "your-api-key",
  baseURL: "https://api.nebux.cloud/v1",
});

const completion = await client.chat.completions.create({
  model: "qwen3-14b",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Recommend me a book" },
    { role: "assistant", content: "Try The Shadow of the Wind" },
    { role: "user", content: "And a similar one?" },
  ],
});

console.log(completion.choices[0].message.content);
RESPUESTA
{
  "id": "chatcmpl-8f3a2b1c9d",
  "object": "chat.completion",
  "created": 1719763200,
  "model": "qwen3-14b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "If you liked it, try Nada, by Carmen Laforet."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 47,
    "completion_tokens": 13,
    "total_tokens": 60
  }
}

Streaming

Establece stream en true para recibir la respuesta como Server-Sent Events, con los tokens llegando de forma incremental a medida que se generan. El stream termina con una línea data: [DONE].

Parámetros

streambooleanobligatorio

Establece en true para transmitir la respuesta como Server-Sent Events.

stream_optionsobjectopcional

Opciones que solo aplican al transmitir.

include_usageboolean

Emite un fragmento final adicional con el uso de tokens de toda la petición.

index.ts
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "your-api-key",
  baseURL: "https://api.nebux.cloud/v1",
});

const stream = await client.chat.completions.create({
  model: "qwen3-14b",
  messages: [{ role: "user", content: "Which running shoes do you recommend?" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
RESPUESTA
data: {
  "id": "chatcmpl-8f3a2b1c9d",
  "object": "chat.completion.chunk",
  "created": 1719763200,
  "model": "qwen3-14b",
  "choices": [{ "index": 0, "delta": { "role": "assistant" }, "finish_reason": null }]
}

data: {
  "id": "chatcmpl-8f3a2b1c9d",
  "object": "chat.completion.chunk",
  "created": 1719763200,
  "model": "qwen3-14b",
  "choices": [{ "index": 0, "delta": { "content": "For asphalt," }, "finish_reason": null }]
}

data: {
  "id": "chatcmpl-8f3a2b1c9d",
  "object": "chat.completion.chunk",
  "created": 1719763200,
  "model": "qwen3-14b",
  "choices": [{ "index": 0, "delta": { "content": " a neutral shoe with good cushioning" }, "finish_reason": null }]
}

data: {
  "id": "chatcmpl-8f3a2b1c9d",
  "object": "chat.completion.chunk",
  "created": 1719763200,
  "model": "qwen3-14b",
  "choices": [{ "index": 0, "delta": {}, "finish_reason": "stop" }]
}

data: [DONE]

Razonamiento

Deja que el modelo piense antes de responder. Está desactivado por defecto: envía chat_template_kwargs con enable_thinking a true para activarlo en una petición. El razonamiento vuelve en reasoning, junto a content y no dentro, así que puedes mostrarlo, registrarlo o ignorarlo. Se factura como tokens de salida igual que el resto de la respuesta, y una respuesta razonada puede gastar varias veces más.

Parámetros

chat_template_kwargsobjectobligatorio

Argumentos extra para la plantilla de prompt del modelo. Solo se admite enable_thinking.

enable_thinkingboolean

true pide al modelo que razone antes de responder. Por defecto, false.

index.ts
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "your-api-key",
  baseURL: "https://api.nebux.cloud/v1",
});

const res = await client.chat.completions.create({
  model: "qwen3-14b",
  messages: [
    { role: "user", content: "A coffee is 1.20. What are 7 with 15% off?" },
  ],
  // chat_template_kwargs is outside the OpenAI library's types,
  // so it travels as an extra request parameter.
  // The other option is calling POST https://api.nebux.cloud/v1/chat/completions
  // directly.
  // @ts-expect-error
  chat_template_kwargs: {"enable_thinking": true},
});

console.log(res.choices[0].message.content);
RESPUESTA
{
  "id": "chatcmpl-6b1d05e37a",
  "object": "chat.completion",
  "created": 1719763200,
  "model": "qwen3-14b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "reasoning": "7 x 1.20 = 8.40. A 15% discount leaves 85%, so 8.40 x 0.85 = 7.14.",
        "content": "7.14 EUR"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 22,
    "completion_tokens": 61,
    "total_tokens": 83
  }
}

Modo JSON

Establece response_format en json_object para forzar que el modelo emita JSON sintácticamente válido. Indica también al modelo que produzca JSON en un mensaje de sistema o de usuario.

Parámetros

response_formatobjectobligatorio

Un objeto que especifica el formato que el modelo debe producir.

typestring

Establece json_object para activar el modo JSON.

index.ts
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "your-api-key",
  baseURL: "https://api.nebux.cloud/v1",
});

const completion = await client.chat.completions.create({
  model: "qwen3-14b",
  messages: [
    { role: "system", content: "Classify each comment as good or bad, keeping its id. Reply as JSON." },
    { role: "user", content: "1: Great! 2: Awful 3: Good 4: Slow" },
  ],
  response_format: { type: "json_object" },
});

console.log(JSON.parse(completion.choices[0].message.content));
RESPUESTA
{
  "id": "chatcmpl-2a7c4e9f10",
  "object": "chat.completion",
  "created": 1719763200,
  "model": "qwen3-14b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "{\"good\": [{\"id\": 1, \"comment\": \"Great!\"}, {\"id\": 3, \"comment\": \"Good\"}], \"bad\": [{\"id\": 2, \"comment\": \"Awful\"}, {\"id\": 4, \"comment\": \"Slow\"}]}"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 58,
    "completion_tokens": 51,
    "total_tokens": 109
  }
}

Herramientas

Proporciona una lista de funciones que el modelo puede invocar. Cuando el modelo decide usar una, devuelve la llamada en tool_calls en lugar de una respuesta de texto; tú ejecutas la función y envías el resultado de vuelta como mensaje tool.

Parámetros

toolsarrayobligatorio

Una lista de funciones que el modelo puede invocar.

typestring

El tipo de herramienta. Actualmente solo se admite function.

functionobject

La definición de la función.

namestring

El nombre de la función a invocar.

descriptionstring

Una descripción de lo que hace la función, usada por el modelo para decidir cuándo invocarla.

parametersobject

Los parámetros de la función, descritos como un objeto JSON Schema.

tool_choicestring | objectopcional

Controla el uso de herramientas: auto, none, required, o una función concreta para forzarla.

index.ts
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "your-api-key",
  baseURL: "https://api.nebux.cloud/v1",
});

const completion = await client.chat.completions.create({
  model: "qwen3-14b",
  messages: [{ role: "user", content: "What's the weather in València?" }],
  tools: [
    {
      type: "function",
      function: {
        name: "get_weather",
        description: "Get the current weather for a location",
        parameters: {
          type: "object",
          properties: { location: { type: "string" } },
          required: ["location"],
        },
      },
    },
  ],
});

console.log(completion.choices[0].message.tool_calls);
RESPUESTA
{
  "id": "chatcmpl-5b1d8e2a34",
  "object": "chat.completion",
  "created": 1719763200,
  "model": "qwen3-14b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_a1b2c3",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\": \"València\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 82,
    "completion_tokens": 19,
    "total_tokens": 101
  }
}

Errores

Las peticiones fallidas devuelven un código de estado HTTP estándar y un cuerpo JSON con un objeto error que describe qué ha ido mal.

Códigos de estado

400invalid_request_errorLa petición estaba mal formada o un parámetro no era válido.
401invalid_api_keyFalta la clave de API o no es válida.
404model_not_foundEl modelo solicitado no existe o no está disponible para tu organización.
429rate_limit_exceededHas superado tu límite de peticiones. Reintenta tras una breve espera.
500server_errorHa ocurrido un error inesperado al procesar la petición.
503engine_overloadedEl servicio está temporalmente sobrecargado. Reintenta tras una breve espera.
Ver la referencia completa de errores
RESPUESTA
{
  "error": {
    "message": "Incorrect API key provided.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Funcionalidades no soportadas

Esta API es compatible con la interfaz de chat completions de OpenAI. Las siguientes funcionalidades de OpenAI no están disponibles.

  • La API de Embeddings.
  • API de Assistants (assistants, threads y runs).
  • Ajuste fino (fine-tuning).
  • La API de Batch.
  • La API de Files y subidas, y los vector stores.
  • Endpoints de audio (síntesis de voz y transcripción).
  • Generación de imágenes.
  • La API de Moderations.
  • La API de Realtime.