Créditos y facturación

Cómo gastan créditos las llamadas a la API, cómo funcionan la retención y el cargo final, cotizar antes de ejecutar, saldo, uso y topes de gasto.

La API gasta los mismos créditos que popnow.ai. No hay plan aparte para la API, ni suscripción, ni mínimo: compra un paquete de créditos cuando necesites más, y los créditos gratis del registro también sirven aquí.

1 crédito = 0,01 USD a la tarifa base. Los paquetes más grandes incluyen créditos extra, así que cada crédito te sale un poco más barato.
Los precios dependen del modelo y de las opciones: por imagen, por segundo de video o audio, por solicitud o por cada 1000 caracteres de voz. La página de cada modelo los muestra.
Las respuestas dan cada importe dos veces: en créditos enteros (credits, maxCredits, availableCredits…) y como cadena en dólares (cost, maxCharge, available…). Usa los campos de créditos; las cadenas en dólares son para contabilidad.

Cómo se cobra una tarea

hold

settlerelease

Los créditos se retienen al aceptar la tarea y se resuelven una sola vez: se cobran según el uso real o se devuelven completos.

Retención. Cuando createTask acepta una tarea, se aparta de tu saldo el precio más alto que puede alcanzar (estimatedCredits). Los créditos retenidos no se pueden gastar dos veces, pero todavía no se cobran.
Cobro o liberación. Cuando la tarea termina:
- succeeded → pagas lo que realmente usó, redondeado hacia arriba a créditos enteros y nunca más que la retención. El resto vuelve a tu saldo.
- failed o expired → se libera toda la retención. No pagas nada.

El registro de la tarea muestra en qué punto está: mientras settled sea false, credits es la retención; cuando settled es true, credits es el cargo final.

Algunos modelos cobran una solicitud que su creador rechazó por motivos de contenido. Cuando pasa, la página del modelo lo indica; en todos los demás casos, fallar es gratis.

Situación	¿Se cobra?
`createTask` rechazado (`400`, `402`, `403`, `429`, `50301`…)	No: ni tarea ni retención
Tarea `succeeded`	Sí, el importe real, con la retención como tope
Tarea `failed` o `expired`	No, salvo el caso de rechazo por contenido de arriba
Se cortó tu conexión después de enviar	No se sabe hasta que lo compruebes: reenvía con el mismo `Idempotency-Key` para encontrar la tarea
Consultar tareas, modelos, saldo o uso	Nunca

Pregunta el precio primero

POST /api/v1/jobs/quote recibe exactamente el cuerpo que enviarías a createTask y devuelve el precio sin crear nada ni retener créditos:

curl -X POST "https://api.popnow.ai/api/v1/jobs/quote" \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "alibaba/wan-3.0/image-to-video", "input": {"image_url": "https://media.popnow.ai/movie/lighthouse.webp", "resolution": "720p", "duration_seconds": 5}}'

{
  "code": 200,
  "msg": "success",
  "data": {
    "quoteId": "q_…",
    "model": "alibaba/wan-3.0/image-to-video",
    "maxCredits": 68,
    "expectedCredits": 68,
    "estimatedCost": "0.68",
    "maxCharge": "0.68",
    "currency": "USD",
    "quantity": "5",
    "unit": "per_second",
    "expiresAt": "2026-10-16T09:25:00Z"
  },
  "request_id": "req_…"
}

maxCredits es lo máximo que puede costar la solicitud: el importe que se retendrá. expectedCredits es lo que suele costar; solo difieren cuando el cargo final depende del resultado, como la duración real de un clip.

Para que el precio no cambie entre mostrárselo a un usuario y ejecutar la tarea, pasa quoteId y expectedCredits (el maxCredits que mostraste) a createTask en un plazo de cinco minutos. Si algo cambió, createTask responde 40901 y no retiene nada; vuelve a cotizar.

Saldo

curl "https://api.popnow.ai/api/v1/chat/credit" \
  -H "Authorization: Bearer $POPNOW_API_KEY"

availableCredits es lo que pueden usar las tareas nuevas, heldCredits lo apartado para tareas en curso y totalCredits la suma de ambos (available, held y total dan los mismos importes en dólares). El nombre de la ruta es histórico y no tiene nada que ver con chat. Cuando el saldo disponible no cubre la retención de una tarea nueva, createTask devuelve 40201.

Uso

GET /api/v1/usage?from=2026-10-01&to=2026-10-16 devuelve, para la clave con la que lo llamas, el número de tareas, cuántas salieron bien y cuántas fallaron, y lo que costaron en créditos: en total (totalCredits), por día y por modelo. Las fechas son UTC, to es exclusivo y el rango es de 92 días como mucho. Solo cuentan los cargos cerrados, así que el total de un día aún puede moverse mientras terminan tareas tardías. Este informe está limitado a 30 solicitudes por minuto; para ver toda la cuenta, usa la página de uso de la consola de la API.

Topes de gasto

Cada clave puede tener un tope diario, mensual y total, configurado en la consola de la API y mostrado en créditos. Una solicitud que superaría un tope devuelve 40202 y no retiene nada. Los topes diarios se reinician a las 00:00 UTC, los mensuales el día 1 a las 00:00 UTC y uno total nunca. Si no los configuras, las claves no tienen topes.

Comprar créditos y reembolsos

Los créditos se compran en la web, no a través de la API. Los paquetes y precios están en la página de precios; la política de reembolsos explica qué se puede reembolsar y cuándo.