Salidas estructuradas

POST https://api.shannon-ai.com/v1/chat/completions

import json
from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1")

response = client.chat.completions.create(
    model="Kimi-K3-3BIT-REAP",
    messages=[
        {"role": "user", "content": "Extract the person: John Doe, 30 years old, engineer."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "occupation": {"type": "string"},
                },
                "required": ["name", "age", "occupation"],
            },
        },
    },
)

# The JSON arrives as text in message.content: parse it, then check it.
try:
    person = json.loads(response.choices[0].message.content)
except json.JSONDecodeError:
    person = None  # ask again, or report the failure

print(person)

import OpenAI from "openai";

const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1" });

const response = await client.chat.completions.create({
  model: "Kimi-K3-3BIT-REAP",
  messages: [
    { role: "user", content: "Extract the person: John Doe, 30 years old, engineer." },
  ],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "person",
      strict: true,
      schema: {
        type: "object",
        properties: {
          name: { type: "string" },
          age: { type: "integer" },
          occupation: { type: "string" },
        },
        required: ["name", "age", "occupation"],
      },
    },
  },
});

// The JSON arrives as text in message.content: parse it, then check it.
let person = null;
try {
  person = JSON.parse(response.choices[0].message.content);
} catch {
  // ask again, or report the failure
}

console.log(person);

curl https://api.shannon-ai.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Kimi-K3-3BIT-REAP",
    "messages": [
      {"role": "user", "content": "Extract the person: John Doe, 30 years old, engineer."}
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "person",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "name": {"type": "string"},
            "age": {"type": "integer"},
            "occupation": {"type": "string"}
          },
          "required": ["name", "age", "occupation"]
        }
      }
    }
  }'

El JSON es el texto de la respuesta, en choices[0].message.content:

{
  "id": "chatcmpl-0c4e7a1b9d2f4e6a8b3c5d7e9f1a2b3c",
  "object": "chat.completion",
  "created": 1791590400,
  "model": "Kimi-K3-3BIT-REAP",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "{\"name\":\"John Doe\",\"age\":30,\"occupation\":\"engineer\"}",
        "reasoning_content": null
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 96,
    "completion_tokens": 19,
    "total_tokens": 115,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 0}
  }
}

Los modos de response_format

response_format es un campo de /v1/chat/completions. Sin él la respuesta es texto normal.

El modo de objeto JSON no necesita esquema. Nombra las claves en el prompt:

{
  "model": "shannon-3",
  "messages": [
    {
      "role": "user",
      "content": "Name the capital of France. Answer as JSON with the keys city and country."
    }
  ],
  "response_format": {"type": "json_object"}
}

Compatibilidad por modelo

GET /v1/models informa lo mismo por id: capabilities.json_schema en todos los modelos, y capabilities.response_format en los modelos de pesos abiertos alojados. Modelos y precios

Palabras clave de esquema admitidas

Lo que un modelo recibe de tu esquema depende del modelo y del endpoint:

El subconjunto de palabras clave de los modelos Shannon en /v1/chat/completions:

En /v1/responses: text.format

/v1/responses escribe la misma solicitud como text.format. El esquema va directamente en format, junto a name y strict, no bajo una clave json_schema. Para el modo de objeto JSON envía {"format": {"type": "json_object"}}.

{
  "model": "Kimi-K3-3BIT-REAP",
  "input": "Extract the person: John Doe, 30 years old, engineer.",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "person",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "age": {"type": "integer"},
          "occupation": {"type": "string"}
        },
        "required": ["name", "age", "occupation"]
      }
    }
  }
}

El JSON es el text de la parte output_text del elemento message:

{
  "output": [
    {
      "id": "msg_7e1d3c5b9a2f4d6e8c0b1a3f5e7d9c2b",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "{\"name\":\"John Doe\",\"age\":30,\"occupation\":\"engineer\"}",
          "annotations": []
        }
      ]
    }
  ]
}

La compatibilidad por modelo y los errores son los mismos que en /v1/chat/completions. API Responses

En /v1/messages: una herramienta como esquema

El formato Messages no tiene un campo de salida estructurada. Para obtener JSON de los mismos modelos, llama a /v1/chat/completions o /v1/responses con la misma clave.

Para quedarte en /v1/messages, describe el objeto como una herramienta: pon tu esquema en input_schema y nombra la herramienta en tool_choice. El input del bloque tool_use es entonces tu objeto, ya analizado. Los modelos de pesos abiertos alojados aplican un tool_choice con nombre.

{
  "model": "Kimi-K3-3BIT-REAP",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Extract the person: John Doe, 30 years old, engineer."
    }
  ],
  "tools": [
    {
      "name": "record_person",
      "description": "Record the extracted person.",
      "input_schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "age": {"type": "integer"},
          "occupation": {"type": "string"}
        },
        "required": ["name", "age", "occupation"]
      }
    }
  ],
  "tool_choice": {"type": "tool", "name": "record_person"}
}

{
  "stop_reason": "tool_use",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_4b8d2f6a1c3e4a5b9d7f0e2c4a6b8d1f",
      "name": "record_person",
      "input": {"name": "John Doe", "age": 30, "occupation": "engineer"}
    }
  ]
}

Comprueba que stop_reason sea tool_use antes de leer el bloque. Llamadas a funciones

Cómo llega el JSON

• El JSON es una cadena. La respuesta no trae un objeto ya analizado a su lado: ejecuta tu analizador de JSON sobre message.content.
• Con stream: true el JSON llega en fragmentos de delta.content. Únelos y analízalos una vez que el stream haya terminado; un fragmento por sí solo no es JSON válido.
• Un modelo de pesos abiertos alojado responde una solicitud con response_format sin texto de razonamiento: reasoning_content es null.

Comprueba lo que recibes

El esquema guía cómo escribe el modelo. La API no compara la respuesta terminada con tu esquema, así que tu código hace la comprobación final:

• Analiza dentro de un manejador de errores, como hace el ejemplo del principio.
• Valida el objeto analizado con el mismo esquema en tu propio código, por ejemplo con una biblioteca de JSON Schema, Pydantic o Zod.
• Una respuesta larga puede terminar antes de que el JSON esté completo. Una respuesta sin stream informa finish_reason solo como stop o tool_calls, así que un error de análisis es la señal. Pregunta de nuevo, o pide un objeto más pequeño.

Errores

Las dos respuestas 400 se envían antes de descontar nada de tu saldo. Manejo de errores