OpenAPI 3.1

Referencia de la API para clientes

Esta página describe las solicitudes y respuestas de inferencia para clientes que admite el servicio. Descargue el documento OpenAPI legible por máquinas para usarlo con herramientas.

Descargar JSON de OpenAPI

Ejemplos de API para modelos

Elige un identificador de modelo publicado, un protocolo de API y un lenguaje para consultar un ejemplo de solicitud. Mantén las claves API de cliente en un servidor de confianza.

Modelo

Lenguaje

Requisitos del protocolo

Las solicitudes compatibles con OpenAI envían POST /chat/completions a la URL base de la API de cliente configurada (por defecto, https://fusionpointai.com/api/v1). Autentícate con Authorization: Bearer y una clave de cliente con permiso de inferencia. La URL predeterminada completa es https://fusionpointai.com/api/v1/chat/completions.

Capacidades admitidas

El endpoint de chat compatible con OpenAI procesa mensajes de texto de forma síncrona. Este endpoint no admite streaming ni llamadas a herramientas.

Instalar un cliente

Instala por separado los clientes de Python y Node.js:

Python: pip install openai anthropic

Node.js: npm install openai @anthropic-ai/sdk

curl 'https://fusionpointai.com/api/v1/chat/completions' \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "Astra 6",
    "messages": [
        {
            "role": "user",
            "content": "Summarize this in one sentence."
        }
    ],
    "temperature": 0.7,
    "max_tokens": 300
}'

Patrones de solicitud

Configurar claves API de forma segura

Crea una clave API de cliente con permiso de inferencia y proporciónasela a un proceso del servidor mediante su gestor de secretos o entorno.

Configura FUSIONPOINTAI_API_KEY en el entorno del servidor; no incrustes la clave en código del navegador ni la confirmes en el control de versiones.
Usa HTTPS y limita la clave a la cuenta y los permisos de inferencia que necesita la aplicación.
Redacta los encabezados Authorization y x-api-key en registros, trazas y solicitudes de soporte; revoca la clave si pudo quedar expuesta.

export FUSIONPOINTAI_API_KEY="YOUR_CUSTOMER_API_KEY"

Seleccionar el identificador exacto del modelo

El campo del modelo es un valor de enrutamiento, no una etiqueta visible. Elige un identificador publicado en el catálogo de modelos activo.

Selecciona un modelo activo o heredado que figure como disponible para inferencia.
Copia exactamente el identificador, incluidos signos de puntuación y sufijos de versión; no deduzcas un ID a partir del nombre del modelo.
Si no se ha publicado ningún identificador, espera a que lo proporcione el catálogo en lugar de inventar uno.

model_id = "Astra 6"
# Use this exact identifier with either protocol.

Enviar mensajes de sistema y de varios turnos

Conserva el orden original de los turnos de conversación y usa solo los roles y formatos de contenido admitidos por el protocolo y el modelo seleccionados.

En las solicitudes compatibles con OpenAI, envía mensajes system, user y assistant como entradas ordenadas con contenido de texto.
En Claude Messages, incluye la instrucción de sistema admitida y los turnos user/assistant ordenados en los campos propios del protocolo.
Conserva solo el contexto de conversación que necesite la aplicación y respeta los límites de contexto del modelo elegido.

response = client.messages.create(
    model="Astra 6",
    max_tokens=512,
    system="Answer in clear, concise German.",
    messages=[
        {"role": "user", "content": "What is an API?"},
        {"role": "assistant", "content": "An API lets software exchange requests and responses."},
        {"role": "user", "content": "Give a practical example."},
    ],
)
for block in response.content:
    if block.type == "text":
        print(block.text)

Solicitar respuestas JSON

Cuando una aplicación necesite una salida estructurada, valida la respuesta conforme a su propio esquema antes de utilizarla.

Usa los controles de salida estructurada que admitan el protocolo y el modelo ascendente elegidos.
Trata el JSON generado como entrada no confiable: analízalo, valida los campos y tipos obligatorios y gestiona las salidas no válidas.
No des por hecho que una combinación de modelo y protocolo admite un modo JSON salvo que la documentación del modelo lo indique.

import json

# JSON is generated content, not trusted application input.
response = client.messages.create(
    model="Astra 6", max_tokens=256,
    messages=[{"role": "user", "content": 'Return only JSON with a string field named "summary". Explain an API in one sentence.'}],
)
text = "".join(block.text for block in response.content if block.type == "text")
try:
    result = json.loads(text)
    if not isinstance(result, dict) or not isinstance(result.get("summary"), str):
        raise ValueError("Unexpected response schema")
    print(result["summary"])
except (json.JSONDecodeError, ValueError) as error:
    print("Handle invalid model output:", error)

Recibir salida SSE en tiempo real

El streaming depende del protocolo y el modelo ascendente seleccionados; una respuesta JSON normal no es un flujo.

El chat compatible con OpenAI devuelve actualmente texto síncrono y no ofrece streaming.
En Claude Messages, usa el modo de streaming cuando lo admita el modelo ascendente seleccionado; el proxy reenvía eventos nativos del servidor.
Procesa los eventos de forma incremental, termina correctamente al recibir fin o error y no trates la salida parcial como una respuesta completa.

# client is the Anthropic client configured above.
with client.messages.stream(
    model="Astra 6", max_tokens=512,
    messages=[{"role": "user", "content": "Explain API authentication."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final_message = stream.get_final_message()
print("\nStop reason:", final_message.stop_reason)

Gestionar herramientas, bloques de contenido y errores

Conserva las estructuras propias del protocolo y define explícitamente el comportamiento de la aplicación ante llamadas a herramientas, contenido multimodal y fallos.

El chat compatible con OpenAI no admite actualmente llamadas a herramientas ni bloques de contenido que no sean texto.
Claude conserva los bloques de contenido nativos y los datos de uso y resultado de herramientas cuando el modelo ascendente seleccionado los admite; valida nombres y argumentos antes de ejecutar herramientas.
Comprueba el estado HTTP y el cuerpo de la respuesta, distingue errores de autenticación, permisos, validación y límites de solicitudes, y reintenta los errores transitorios con espera incremental.

import json
from datetime import datetime, timezone
from anthropic import APIError

messages = [{"role": "user", "content": "What time is it in UTC?"}]
tools = [{
    "name": "current_utc_time", "description": "Read the current UTC time.",
    "input_schema": {"type": "object", "properties": {}, "additionalProperties": False},
}]
try:
    reply = client.messages.create(model="Astra 6", max_tokens=256, messages=messages, tools=tools)
    results = []
    for block in reply.content:
        if block.type == "tool_use":
            if block.name != "current_utc_time" or block.input != {}:
                raise ValueError("Unapproved tool request")
            results.append({"type": "tool_result", "tool_use_id": block.id,
                            "content": json.dumps({"utc": datetime.now(timezone.utc).isoformat()})})
    if results:
        messages.append({"role": "assistant", "content": reply.content})
        messages.append({"role": "user", "content": results})
        reply = client.messages.create(model="Astra 6", max_tokens=256, messages=messages, tools=tools)
    print("".join(block.text for block in reply.content if block.type == "text"))
except APIError as error:
    # Log status only; never log keys or private prompts.
    print("API request failed:", getattr(error, "status_code", None))

Preguntas frecuentes

¿Puedo usar el nombre visible del modelo en una solicitud?

Usa solo el identificador exacto publicado para inferencia. El nombre visible no sirve para el enrutamiento y nunca debes inventar un identificador no publicado.

¿Qué variable de entorno contiene la clave de cliente?

Usa FUSIONPOINTAI_API_KEY con ambos protocolos. Conserva su valor en un entorno de servidor de confianza y fuera del código del cliente y los registros.

¿Qué URL debe usar el cliente OpenAI?

Usa la URL base de API de cliente configurada, cuyo valor predeterminado es https://fusionpointai.com/api/v1. El endpoint de chat completions añade /chat/completions.

¿Por qué la URL base del SDK Claude es distinta de la de cURL?

El SDK de Anthropic añade /v1/messages, por lo que su URL base debe ser https://fusionpointai.com/api. Una solicitud HTTP directa usa la URL completa /api/v1/messages.

¿El chat compatible con OpenAI admite streaming o herramientas?

No. El endpoint actual solo admite mensajes de texto síncronos; no ofrece streaming ni llamadas a herramientas.

¿Todos los modelos Claude admiten bloques, herramientas o streaming?

No. Estas funciones nativas se conservan cuando el modelo ascendente seleccionado las admite. Comprueba sus capacidades y gestiona las solicitudes no admitidas.

Claude Messages · `POST /messages`

Las solicitudes Claude Messages envían POST /api/v1/messages. Incluye la clave de cliente en x-api-key y configura anthropic-version como 2023-06-01. La URL base del SDK de Anthropic es https://fusionpointai.com/api porque el SDK añade /v1/messages; también se admite autenticación Bearer.

El proxy Claude Messages conserva bloques de contenido nativos, datos de herramientas y streaming SSE real del servidor cuando el modelo ascendente seleccionado admite esas funciones.

Campo	Tipo	Obligatorio	Restricciones
`model`	`string`	Sí	`{"minLength":1,"maxLength":160}`
`max_tokens`	`integer`	Sí	`{"minimum":1,"maximum":100000}`
`messages`	`array`	Sí	`{"minItems":1,"maxItems":100,"items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string","maxLength":80}},"additionalProperties":true}}]}}}}`
`system`	`string \| array`	No	`{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","required":["type","text"],"properties":{"type":{"const":"text"},"text":{"type":"string"}},"additionalProperties":true}}]}`
`stream`	`boolean`	No	`{"default":false}`
`temperature`	`number`	No	`{"minimum":0,"maximum":1}`
`top_p`	`number`	No	`{"minimum":0,"maximum":1}`
`top_k`	`integer`	No	`{"minimum":0,"maximum":100000}`
`stop_sequences`	`array`	No	`{"items":{"type":"string"}}`
`tools`	`array`	No	`{"items":{"type":"object","additionalProperties":true}}`
`tool_choice`	`object`	No	`{"additionalProperties":true}`
`thinking`	`object`	No	`{"additionalProperties":true}`
`metadata`	`object`	No	`{"additionalProperties":true}`
`output_config`	`object`	No	`{"additionalProperties":true}`
`service_tier`	`string`	No	`[]`

{
    "id": "msg_example",
    "type": "message",
    "role": "assistant",
    "model": "Astra 6",
    "content": [
        {
            "type": "text",
            "text": "A concise answer to the supplied question."
        }
    ],
    "stop_reason": "end_turn",
    "stop_sequence": null,
    "usage": {
        "input_tokens": 12,
        "output_tokens": 10
    }
}

{"type":"error","error":{"type":"authentication_error","message":"Invalid or missing API key."}}

Inicio rápido con SDK

Use la URL base de producción con un cliente compatible de Python o Node.js, o envíe la misma solicitud JSON con cURL.

URL base de la API: https://fusionpointai.com/api/v1

Envíe la clave de API de cliente en el encabezado Authorization: Bearer. La clave debe tener el ámbito ai:inference y acceso al servicio desde la cuenta. Guárdela en un servidor de confianza.

# Install the client for your application language.
# Python:
python -m pip install openai
# Node.js:
npm install openai

# Bash: enter the key without storing it in shell history.
read -rs -p 'FusionPointAI API key: ' FUSIONPOINTAI_API_KEY
export FUSIONPOINTAI_API_KEY
printf '\n'
# After finishing:
# unset FUSIONPOINTAI_API_KEY

curl 'https://fusionpointai.com/api/v1/chat/completions' \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "Jurassic-2",
    "messages": [
        {
            "role": "user",
            "content": "Summarize this in one sentence."
        }
    ],
    "temperature": 0.7,
    "max_tokens": 300
}'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FUSIONPOINTAI_API_KEY"],
    base_url="https://fusionpointai.com/api/v1",
)

response = client.chat.completions.create(
    model="Jurassic-2",
    messages=[{"role": "user", "content": "Summarize this in one sentence."}],
    temperature=0.7,
    max_tokens=300,
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FUSIONPOINTAI_API_KEY,
  baseURL: "https://fusionpointai.com/api/v1",
});

const response = await client.chat.completions.create({
  model: "Jurassic-2",
  messages: [{ role: "user", content: "Summarize this in one sentence." }],
  temperature: 0.7,
  max_tokens: 300,
});
console.log(response.choices[0].message.content);

OpenAI · Campos de la solicitud

Los valores de model son los identificadores exactos registrados y publicados actualmente para inferencia. Si no hay ninguno publicado, consulte el catálogo de proveedores antes de enviar una solicitud.

Campo	Tipo	Obligatorio	Restricciones
`model`	`string`	Sí	Hasta 160 caracteres; use un identificador exacto publicado.
`messages`	`array`	Sí	De 1 a 100 mensajes, enviados en orden.
`messages[].role`	`string`	Sí	system, user o assistant.
`messages[].content`	`string`	Sí	Hasta 100 000 caracteres por mensaje.
`temperature`	`number`	No	De 0 a 2.
`max_tokens`	`integer`	No	De 1 a 100 000; el modelo puede imponer un límite inferior.

Respuesta correcta

Una respuesta JSON correcta contiene id, object (chat.completion), created, model y choices. Cada choice incluye index, un mensaje del asistente y finish_reason. También puede devolverse el uso de tokens.

{
    "id": "chatcmpl_example",
    "object": "chat.completion",
    "created": 1700000000,
    "model": "Jurassic-2",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "A concise summary of the supplied text."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 12,
        "completion_tokens": 10,
        "total_tokens": 22
    }
}

Campo	Tipo	Significado
`id`	`string`	Identificador único de la respuesta completa.
`object`	`string`	Tipo de respuesta: chat.completion.
`created`	`integer`	Hora de creación en formato de marca de tiempo Unix.
`model`	`string`	Identificador del modelo utilizado para generar la respuesta.
`choices`	`array`	Alternativas de respuesta con un mensaje del asistente y el motivo de finalización.
`usage`	`object`	Recuento de tokens, si se devuelve.

Límites de solicitudes y errores

Las suscripciones activas de clientes no descuentan las solicitudes ni los tokens de una cuota; las claves de sandbox usan la asignación mensual publicada. Siguen aplicándose las ventanas de contexto, los límites de salida y los controles temporales de tráfico. Chat Completions ofrece texto síncrono; Claude Messages conserva los bloques de contenido nativos, las herramientas y SSE que admita el modelo. Antes de enviar solicitudes, consulta los esquemas de operación por separado.

La operación de chat devuelve los errores de validación y del proveedor en un objeto error. El middleware de autenticación y ámbitos puede devolver, en su lugar, un campo message de nivel superior; el estado y el formato dependen de la capa que haya rechazado la solicitud.

Estado HTTP	Significado
`200`	La respuesta se ha generado correctamente.
`400`	El cuerpo de la solicitud o uno de sus parámetros no es válido.
`401`	La clave de API bearer falta o no es válida.
`403`	Faltan el ámbito requerido para la clave o el acceso de la cuenta.
`429`	Se ha aplicado el límite de la aplicación o un control temporal del tráfico ascendente; reintente con pausas.
`500`	El servicio no ha podido devolver una respuesta completa utilizable.