Campos e unidades
schemaVersion identifica o contrato. version identifica o conteúdo do catálogo; verifiedAt informa a verificação da fonte e fresh informa se ela ainda é recente. modelCount conta IDs distintos de modelos, sem aliases e variantes.
Em cada modelo, id identifica a base e requestId indica a variante para a tarifa publicada. input e output são tarifas USD/1M tokens. cacheRead e cacheWrite são dimensões separadas; null é desconhecido. contextTokens é a janela informada, sem presumir o máximo de saída. tiers descreve limites de entrada e fatores públicos de preço.
Cache e atualização
O endpoint publica Cache-Control com max-age de 15 segundos e ETag da representação. Reenvie If-None-Match para obter 304 quando não houver alteração. A data pode mudar mesmo quando a versão de conteúdo se mantém: uma nova verificação sem mudança de preço não cria uma nova tarifa.
Depois de 15 minutos sem verificação, fresh fica falso e as calculadoras desta camada suspendem estimativas. Preserve a última representação com sua data e não apresente dado desconhecido como zero. Não existe promessa de disponibilidade ou SLA deste endpoint.
Consumo de leitura e canonical
Use GET sem chave de API. O header Link aponta para /modelos como página canônica para pessoas. A exportação recebe noindex para evitar competição com a página HTML; ela continua acessível a consumidores técnicos.
O registro existente em /.well-known/models.json também lista variantes e atalhos aceitos. Não use a quantidade de entradas desse registro como quantidade de modelos. Não envie prompts, chaves, cookies ou informações pessoais em parâmetros de descoberta.