Catálogo de modelos e schemas

createTask.model recebe exatamente o model retornado pela resposta autenticada de GET /api/v1/models. Seu input é definido pelo inputSchema atual do mesmo item. Essa resposta em tempo de execução é a única fonte confiável para um ID que pode ser chamado.

Nos exemplos desta página, MODEL_ID_FROM_CATALOG é um marcador, não um modelo real: substitua-o por um valor de model do seu catálogo em tempo real. A consulta ao catálogo é gratuita.

Selecionar um modelo e uma entrada validada

Os schemas das solicitações variam entre modelos. Por isso, a forma segura de obter um exemplo executável é selecionar juntos um modelo disponível e um de seus exemplos validados pelo 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 exemplo contém um input completo que o servidor já validou com o schema atual e pode ser enviado sem alterações.

Consultar o catálogo por 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"

A lista não é paginada: uma resposta contém todos os modelos visíveis para sua chave que correspondem aos filtros. Todos os parâmetros são opcionais.

O endpoint de um único modelo, GET /api/v1/models/{model}, sempre inclui inputSchema e examples; includeSchema e includeExamples só afetam a lista. As barras do ID podem permanecer como estão; aplique codificação percentual somente se seu cliente HTTP tratar um parâmetro de caminho como um único segmento. Um modelo inexistente ou que não é oferecido no momento retorna 404.

Uma resposta 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"
}

Os preços acima são ilustrativos. inputSchema e examples só aparecem nos itens da lista quando solicitados.

Campos que os clientes devem usar

mature e policyTier são rótulos informativos. Não participam da decisão de aceitar uma solicitação.

Como interpretar preços

Cada entrada de pricing representa uma faixa de preço:

startingPrice é a entrada mais barata, não o preço das suas configurações. Os campos que selecionam uma faixa são listados em inputSchema["x-pricing"].variantFields, quando presente; caso contrário, são os campos marcados com x-ui.affects_price: true, exceto quantityField. Um campo omitido usa seu default do schema.

• Modelos de mídia: seu custo é price × quantity, em que a quantidade é o valor de quantityField na entrada, ou uma unidade quando quantityField está vazio. Alguns endpoints acrescentam uma cobrança separada por entrada adicional, geralmente por imagem de referência. Considere-a parte real da cobrança, não um detalhe de arredondamento: em um endpoint de edição que aceita uma lista de imagens de referência, preencher a lista pode multiplicar o valor, enquanto unit, quantity, variant e o price da faixa permanecem exatamente iguais aos de uma imagem única. Assim, a fórmula acima informa um valor menor que o real sem nenhum sinal visível. A indicação legível por máquina é um campo marcado com x-ui.affects_price: true que não é o quantityField nem aparece em x-pricing.variantFields: ele altera o valor sem selecionar uma faixa. Nesses endpoints, trate pricing como valor mínimo e obtenha o total por um orçamento.
• Modelos de texto (per_1k_tokens): um número só não descreve a cobrança. price é apenas a tarifa de tokens de saída por 1.000 tokens. Tokens de entrada e de entrada em cache têm tarifas próprias, geralmente menores, e são cobrados conforme o uso medido de cada chamada. Não multiplique price pelo total de tokens. Os preços por milhão de tokens de entrada, entrada em cache e saída aparecem na página de cada modelo e em price.perMillionTokens no catálogo público.

Para saber o valor de uma solicitação exata na API nativa antes de pagar, use POST /api/v1/jobs/quote. A cobrança final aparece no registro da tarefa, em cost com settled: true, e em Faturamento.

Cache do catálogo

• A resposta do catálogo pode ser mantida em cache por até 60 segundos (Cache-Control: private, max-age=60). Use somente um cache privado por conta: os preços são específicos da conta, portanto nunca os coloque em um cache de CDN público ou compartilhado.
• Além disso, não consulte o catálogo antes de cada tarefa. Leituras do catálogo usam a capacidade de leitura da conta, independentemente do envio de tarefas. Consultar o catálogo antes de cada chamada ainda desperdiça a capacidade de leitura; Veja Limites de solicitações.
• Atualize-o periodicamente, por exemplo a cada poucos minutos, após um erro de validação 400 e quando o envio de uma tarefa para aquele modelo for recusado.
• Guarde a version e o updatedAt do registro usado para identificar mudanças em uma consulta posterior.
• Nunca distribua um schema fixo no código nem use uma página estática como alternativa quando o catálogo em tempo real não tiver nenhum item disponível para chamadas.

Regras compartilhadas de Schema e Playground

inputSchema usa JSON Schema 2020-12. As palavras-chave padrão controlam a validação no servidor; o objeto x-ui de cada propriedade apenas descreve a ordem, a apresentação e as indicações de atualização de orçamento do Playground. Os clientes devem ignorar extensões de apresentação desconhecidas, que nunca substituem required, enumerações, limites ou condições. Veja o contrato Spicy Schema completo.

Criar sua própria tabela de parâmetros por modelo

Este site não inclui tabelas estáticas de parâmetros por modelo. Isso não é falta de cuidado: modelos e campos mudam toda semana, qualquer cópia fixa fica desatualizada, e usar um parâmetro antigo custa um erro 400 ou um preço incorreto. Os parâmetros têm uma única fonte: o inputSchema retornado pelo catálogo. O Playground renderiza esse mesmo documento, e o SDK o usa para validar.

Como transformar cada parte do schema em uma tabela

As condições só aparecem na raiz de inputSchema, em dois formatos: anyOf, em que cada condição lista somente campos required (“forneça pelo menos um destes”), e allOf, em que cada condição é if → then (“se fornecer A, você precisa fornecer B”). Não as deduza pela família nem espere oneOf, not ou dependentSchemas. Novos endpoints seguem os campos canônicos do Spicy Schema; os antigos seguem seu schema em tempo real.

Consultar o schema

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,
  }));

Esse exemplo se limita intencionalmente a valores escalares: deixa values vazio para uma lista, pois uma lista define o que aceita em items, minItems e maxItems, não em enum ou em um intervalo. Amplie-o antes de publicar: uma linha que mostra apenas array, sem formato das entradas nem limite de tamanho, é uma linha que não permite ao leitor agir.

O registro de um modelo também retorna examples: cada exemplo é uma entrada completa já validada no servidor com o schema atual. Portanto, funciona tanto como exemplo mínimo executável na sua documentação quanto como corpo de solicitação pronto para envio. Isso é mais seguro que montar um exemplo manualmente, pois um exemplo escrito à mão fica desatualizado quando o schema muda; examples acompanha a mudança.

O mesmo código atende qualquer modelo alterando modelId e não perde a validade quando adicionamos novos modelos. Para gerar uma tabela do catálogo inteiro, percorra os items de GET /api/v1/models?includeSchema=1 e mantenha-os em cache conforme Cache do catálogo.

Texto de ajuda mais longo que description

description é uma frase, dimensionada para um rótulo de formulário. Quando um parâmetro exige mais explicação, o catálogo público oferece uma segunda nota por parâmetro:

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

O registro de um modelo retorna paramNotes, um objeto cujas chaves são os nomes dos parâmetros, escrito em qualquer um dos dez idiomas da documentação via locale. Ele contém o que não cabe em um rótulo: com base em que um valor é medido, qual configuração deixa uma chamada perceptivelmente mais lenta e quais entradas são aceitas pelo schema, mas ainda produzem um resultado abaixo do esperado. Para um parâmetro que aponta para um arquivo hospedado por você, geralmente é o único lugar que informa se buscamos esse arquivo, quando o buscamos e o que acontece se ele for inutilizável.

Há dois limites: paramNotes está no catálogo público, que não exige chave, e não no GET /api/v1/models autenticado; consulte-o separadamente e mantenha-o em cache junto ao schema. Além disso, é texto explicativo, nunca uma regra: inputSchema continua sendo a única referência que determina se uma solicitação é aceita.