Facturación

Fondos promocionales y línea de crédito

GET /api/v1/chat/credit puede incluir funding para separar fondos prepagados, asignaciones promocionales y crédito aprobado. Si una respuesta anterior no lo incluye, no lo interpretes como cero. Usa client.getBalance() o spicyapi balance --json. Los importes son cadenas decimales exactas en USD y las fechas usan RFC3339.

prepaidAvailableUsd son fondos prepagados disponibles; grantAvailableUsd suma las asignaciones vigentes. Cada elemento de grants muestra availableUsd, heldUsd, spentUsd, status, startsAt, expiresAt y modelSlugs. Una lista vacía admite todos los modelos. Solo se pueden usar dentro de su vigencia y para los modelos indicados; no se pueden retirar. La lista contiene hasta 100 asignaciones, primero las que tienen saldo restante o reservado y, dentro de cada grupo, las más recientes. grantsHasMore indica que hay más registros: no uses el subtotal visible como total de la cuenta.

credit.limitUsd es el límite aprobado, no dinero en la cuenta. credit.availableUsd es el crédito restante, usedUsd la deuda liquidada pendiente de pago y heldUsd la parte reservada. El vencimiento, la desactivación o superar el límite restringen nuevos usos, pero no eliminan la deuda. available puede ser negativo al usar crédito aprobado; no rechaces solicitudes basándote solo en ese signo. Un cashShortfallUsd positivo es un déficit por recuperación de un pago externo que no puede cubrirse con fondos promocionales ni crédito. El servidor decide la admisión.

Los descuentos determinan el precio; las asignaciones y el crédito, cómo se financia. Las reservas liberadas vuelven a su fuente original sin reactivar fondos vencidos o revocados. Los cambios requieren aprobación manual. Contacta con soporte: la API pública no permite aumentarte el saldo. En el libro mayor, grant_expire indica vencimiento y grant_revoke revocación.

Uso de la clave API actual

GET /api/v1/usage agrega solo las tareas de la clave API utilizada para autenticarse. from y to son fechas UTC en formato YYYY-MM-DD. El intervalo [from,to) incluye el inicio y excluye el final, con un máximo de 92 días. Por defecto, to es la fecha de mañana en UTC y from es siete días antes de to. totalSpend y cada spend son cadenas decimales en USD que suman solo cargos reales ya liquidados, sin reservas pendientes. La agrupación usa la fecha de creación de la tarea, por lo que una liquidación tardía puede cambiar importes de días anteriores. No representa el saldo ni el presupuesto restante de la clave.

Descuentos de cuenta y promociones

Las ofertas pueden aplicarse a todos los usuarios o a una cuenta concreta, para todos los modelos o una selección. Las ofertas permanentes duran hasta su desactivación; las temporales rigen entre su inicio y fin reales. Los precios exclusivos requieren iniciar sesión en esa cuenta o solicitar la cotización con su clave API.

Los descuentos no se acumulan: se aplica automáticamente el menor precio disponible. Con un precio base de $10, una promoción del 10% y un descuento de cuenta del 20%, el precio es $8. Al terminar una oferta, las nuevas cotizaciones usan la mejor oferta vigente o el precio normal.

La cuenta atrás no reserva un precio. Consulta jobs/quote con tu identidad y todos los parámetros; renueva la cotización si cambian la oferta, el precio o las entradas. Una tarea aceptada conserva el precio fijado aunque la promoción termine durante su ejecución. El cobro final no supera el importe reservado.

Los descuentos se aplican automáticamente al consumo de la API, no al importe de las recargas, y no son devoluciones por recargar. Los presupuestos diarios o mensuales extrapolan el precio actual; una promoción puede terminar antes de que acabe ese período. Comprueba también su fecha de fin.

Unidades de facturación

pricing[].unit es per_image, per_second, per_request o per_1k_tokens. Lee quantityField y pricing[].variant del catálogo en lugar de adivinar campos de entrada.

Reserva, liquidación y liberación

createTask reserva estimatedCost. succeeded se liquida según el uso real; failed, expired y los registros canceled históricos liberan todo. Una tarea nueva aceptada no se puede cancelar. La tarea y la reserva se crean en una transacción y la liquidación de cada tarea termina exactamente una vez.

Saldo y topes

GET /api/v1/chat/credit devuelve available, held y total. Saldo insuficiente es 40201; los topes diario, mensual y acumulado de la clave, y el tope diario de la plataforma, son 40202. Los topes diarios se reinician a medianoche UTC y los mensuales el día 1 a medianoche UTC; un tope acumulado nunca se reinicia. Un 0 explícito significa sin límite.

Libro mayor

El ledger es append-only y registra por separado topup, bonus, hold, settle, refund, adjust y chargeback. Estos movimientos de saldo no se borran con el contenido de las tareas y siguen visibles en el historial de facturación.