Catálogo de modelos y esquemas

createTask.model recibe el valor exacto de model devuelto por la respuesta autenticada de GET /api/v1/models. Su input se define en el inputSchema actual de esa misma entrada. Esa respuesta en tiempo de ejecución es la única fuente válida para obtener un ID que pueda ejecutarse.

En los ejemplos de esta página, MODEL_ID_FROM_CATALOG es un marcador de posición, no un modelo real: sustitúyelo por un valor de model de tu propio catálogo en vivo. Consultar el catálogo es gratis.

Seleccionar un modelo y sus entradas validadas

Los esquemas de solicitud varían entre modelos, así que el método seguro consiste en seleccionar juntos un modelo en vivo y uno de sus ejemplos validados por el servidor:

const response = await fetch(
  'https://api.spicyapi.ai/api/v1/models?includeSchema=1&includeExamples=1',
  { headers: { Authorization: `Bearer ${process.env.SPICY_API_KEY}` } },
);
const envelope = await response.json();
if (!response.ok || envelope.code !== 200) throw new Error(envelope.msg);

const selected = envelope.data.items.find(
  (item) => item.enabled && item.available && item.examples?.length,
);
if (!selected) throw new Error('No callable model with a validated example');

const createTaskBody = {
  model: selected.model,
  input: selected.examples[0].input,
};

Cada ejemplo es un input completo que el servidor ya validó con el esquema actual, por lo que puedes enviarlo sin cambios.

Consultar el catálogo desde tu código

GET /api/v1/models
GET /api/v1/models/{model}

curl "https://api.spicyapi.ai/api/v1/models?modality=video" \
  -H "Authorization: Bearer $SPICY_API_KEY"

La lista no está paginada: una respuesta contiene todos los modelos que tu clave puede ver y que coinciden con los filtros. Todos los parámetros son opcionales.

El endpoint de un solo modelo, GET /api/v1/models/{model}, siempre incluye inputSchema y examples; includeSchema e includeExamples solo afectan a la lista. Las barras del ID pueden mantenerse tal cual; codifícalas porcentualmente solo si tu cliente HTTP trata un parámetro de ruta como un único segmento. Un modelo que no exista o no se ofrezca actualmente devuelve 404.

Una respuesta de lista abreviada:

{
  "code": 200,
  "msg": "success",
  "data": {
    "total": 1,
    "items": [
      {
        "model": "MODEL_ID_FROM_CATALOG",
        "family": "…",
        "displayName": "…",
        "provider": "…",
        "modality": "video",
        "tasks": ["image-to-video"],
        "async": true,
        "enabled": true,
        "available": true,
        "availability": "available",
        "taskTimeoutSeconds": 1200,
        "maxOutputDurationSeconds": 10,
        "quantityField": "duration_seconds",
        "pricing": [
          { "variant": "generate_audio=false;resolution=720p", "unit": "per_second", "price": "0.05", "currency": "USD" },
          { "variant": "generate_audio=true;resolution=720p", "unit": "per_second", "price": "0.08", "currency": "USD" }
        ],
        "startingPrice": { "variant": "generate_audio=false;resolution=720p", "unit": "per_second", "price": "0.05", "currency": "USD" },
        "badges": ["audio_output"],
        "relatedModels": [],
        "version": "v1",
        "updatedAt": "2026-09-16T16:47:57Z"
      }
    ]
  },
  "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2"
}

Los precios anteriores son ilustrativos. inputSchema y examples solo aparecen en las entradas de la lista cuando los solicitas.

Campos que debe utilizar el cliente

mature y policyTier son etiquetas informativas. No intervienen en la aceptación de una solicitud.

Cómo leer los precios

Cada entrada de pricing es un nivel de precio:

startingPrice es la entrada más económica, no el precio de tus ajustes. Los campos que seleccionan un nivel aparecen en inputSchema["x-pricing"].variantFields cuando existe; de lo contrario, son los marcados con x-ui.affects_price: true (salvo quantityField). Un campo omitido utiliza su default del esquema.

• Modelos de medios: el costo es price × quantity, donde la cantidad es el valor de quantityField en tu entrada, o una unidad si quantityField está vacío. Algunos endpoints añaden un cargo separado por cada entrada adicional, normalmente por cada imagen de referencia. Es una parte real de la factura, no un detalle de redondeo: en un endpoint de edición que acepta un array de imágenes de referencia, llenar ese array puede multiplicar el importe, mientras que unit, quantity, variant y el price del nivel permanecen exactamente iguales que para una sola imagen. Por eso, el cálculo anterior subestima el costo sin una señal visible. La señal legible por máquinas es un campo marcado con x-ui.affects_price: true que no es quantityField ni aparece en x-pricing.variantFields: modifica el importe sin seleccionar un nivel. En esos endpoints, interpreta pricing como un mínimo y obtén el importe de una cotización.
• Modelos de texto (per_1k_tokens): un solo número no describe el cargo. price es únicamente la tarifa de tokens de salida por cada 1,000 tokens. Los tokens de entrada y de entrada en caché tienen sus propias tarifas, normalmente menores, y se facturan según el uso medido de cada llamada. No multipliques price por el total de tokens. Los precios por millón de tokens de entrada, entrada en caché y salida aparecen en la página de cada modelo y en price.perMillionTokens del catálogo público.

Para conocer el importe de una solicitud exacta en la API nativa antes de pagar, utiliza POST /api/v1/jobs/quote. Los cargos definitivos aparecen en el registro de la tarea (cost con settled: true) y en Facturación.

Caché del catálogo

• La respuesta del catálogo puede guardarse en caché durante un máximo de 60 segundos (Cache-Control: private, max-age=60). Utiliza únicamente una caché privada por cuenta: los precios son específicos de tu cuenta, así que nunca la pongas detrás de una caché CDN compartida o pública.
• Aparte de eso, no vuelvas a consultarlo antes de cada tarea. Las consultas del catálogo utilizan la capacidad de lectura de la cuenta, de forma independiente del envío de tareas. Consultar el catálogo antes de cada llamada sigue desperdiciando capacidad de lectura; consulta Límites de solicitudes.
• Actualízalo periódicamente (por ejemplo, cada pocos minutos), después de un error de validación 400 y cuando se rechace el envío de una tarea para ese modelo.
• Conserva la version y el updatedAt del registro utilizado para saber si una consulta posterior contiene cambios.
• Nunca distribuyas una copia del esquema fijada en el código ni recurras a una página estática cuando el catálogo en vivo no tenga una entrada que pueda ejecutarse.

Reglas compartidas del esquema y Playground

inputSchema utiliza JSON Schema 2020-12. Las palabras clave estándar controlan la validación del servidor; el objeto x-ui de cada propiedad solo describe el orden, la presentación y las indicaciones para renovar cotizaciones en Playground. Los clientes deben ignorar las extensiones de presentación desconocidas, que nunca sustituyen required, las enumeraciones, los límites ni las ramas condicionales. Consulta el contrato completo de Spicy Schema.

Crear tu propia tabla de parámetros por modelo

Este sitio no incluye una tabla de parámetros por modelo. No es por falta de trabajo: los modelos y campos cambian cada semana, cualquier copia estática se desactualiza y leer un parámetro antiguo puede causar un 400 o un precio incorrecto. Los parámetros tienen una sola fuente: el inputSchema devuelto por el catálogo. Playground muestra ese mismo documento y el SDK valida con él.

Cómo representar cada parte del esquema en una tabla

Las ramas condicionales solo aparecen en la raíz de inputSchema y tienen dos formas: anyOf, donde cada rama enumera únicamente campos required («proporciona al menos uno de estos»), y allOf, donde cada rama es if → then («si proporcionas A, debes proporcionar B»). No las deduzcas de la familia ni esperes oneOf, not o dependentSchemas. Los endpoints nuevos usan los campos canónicos de Spicy Schema; los antiguos siguen su esquema en vivo.

Cómo obtenerlo

const modelId = 'MODEL_ID_FROM_CATALOG'; // the exact `model` value from GET /api/v1/models
const res = await fetch(`https://api.spicyapi.ai/api/v1/models/${modelId}`, {
  headers: { Authorization: `Bearer ${process.env.SPICY_API_KEY}` },
});
const { data } = await res.json();
const schema = data.inputSchema;

const rows = Object.entries(schema.properties)
  .sort(([, a], [, b]) => (b['x-ui']?.order ?? 0) - (a['x-ui']?.order ?? 0))
  .map(([name, prop]) => ({
    name,
    required: (schema.required ?? []).includes(name),
    type: prop.type,
    description: prop.description,
    values: prop.enum
      ? prop.enum.map((v) => prop['x-ui']?.enum_labels?.[v] ?? v)
      : prop.minimum !== undefined || prop.maximum !== undefined
        ? [`${prop.minimum ?? ''}–${prop.maximum ?? ''}${prop['x-ui']?.unit ?? ''}`]
        : [],
    default: prop.default,
    affectsPrice: prop['x-ui']?.affects_price === true,
    advanced: prop['x-ui']?.advanced === true,
  }));

Este ejemplo se limita deliberadamente a valores escalares: deja values vacío en los arrays porque estos indican lo que aceptan en items, minItems y maxItems, no en enum ni en un rango. Amplíalo antes de publicarlo: una fila que muestra un parámetro como un simple array, sin forma de sus entradas ni límite de longitud, no da al lector información suficiente para utilizarlo.

El registro de un solo modelo también devuelve examples: cada uno es una entrada completa ya validada por el servidor con el esquema actual, así que sirve como ejemplo mínimo ejecutable en tus documentos y como cuerpo de solicitud que puedes enviar sin cambios. Es más seguro que componer uno a mano: un ejemplo manual se desactualiza cuando cambia el esquema, mientras que examples se mantiene validado.

El mismo código sirve para cualquier modelo cambiando modelId y no pierde validez cuando añadimos modelos nuevos. Para generar una tabla de todo el catálogo, recorre items de GET /api/v1/models?includeSchema=1 y guárdala en caché como se explica en Caché del catálogo.

Ayuda más detallada que description

description es una frase breve, pensada para un formulario. Cuando un parámetro necesita más explicación, el catálogo público incluye una segunda nota por parámetro:

curl "https://api.spicyapi.ai/console/v1/catalog/models/MODEL_ID_FROM_CATALOG?locale=en"

El registro de un solo modelo devuelve paramNotes, un objeto cuyas claves son los nombres de los parámetros, escrito en cualquiera de los diez idiomas de documentación mediante locale. Allí se explican cuestiones que no caben en una etiqueta: contra qué se mide realmente un valor, qué ajuste hace notablemente más lenta una llamada y qué entradas acepta el esquema pero pueden producir un resultado decepcionante. Si el parámetro apunta a un archivo alojado por ti, normalmente es el único lugar que indica si lo descargamos, cuándo lo hacemos y qué ocurre si no puede utilizarse.

Hay dos límites: paramNotes pertenece al catálogo público, que no requiere una clave, y no al GET /api/v1/models autenticado, por lo que debes consultarlo por separado y guardarlo en caché junto al esquema. Además, es texto explicativo, nunca una regla: inputSchema sigue siendo lo único que determina si una solicitud se acepta.