Documentación API y MCP

El acceso gratuito a la API es una función en la nube separada de la herramienta del navegador. Proporciona 500 créditos por mes UTC sin tarjeta después de iniciar sesión con una cuenta @gmail.com verificada por Google y pasar Turnstile, sujeto a un presupuesto mensual de cómputo gratuito de $20.

Crea una clave API desde la página de ajustes de la cuenta después de la activación. Todas las claves de la cuenta comparten el mismo saldo de créditos, límites de velocidad y límites de trabajos sin terminar. Cuando se agota el presupuesto de cómputo gratuito, los nuevos trabajos gratuitos se pausan hasta la hora de reinicio mostrada; los trabajos Developer de pago y la compresión local en el navegador continúan por separado.

Envía una solicitud multipart con un archivo GIF y un campo options que contiene JSON. El modo objetivo usa bytes decimales en targetBytes; no envíes campos mode o targetBytes separados en el formulario.

Cada solicitud de creación debe incluir un Idempotency-Key con alcance de cuenta. Reutilizar la misma clave con el mismo archivo y opciones devuelve el trabajo original sin reservar créditos otra vez.

La respuesta de creación contiene un id de nivel superior. Guárdalo como JOB_ID y úsalo en la URL de estado; no está dentro de una propiedad job. La respuesta de creación por sí sola no contiene un enlace de descarga. Consulta el endpoint de estado incluso cuando la creación reproduce un trabajo ya completado. Sustituye YOUR_JOB_ID en el ejemplo por ese id, luego copia result.downloadUrl de una respuesta succeeded en DOWNLOAD_URL antes de ejecutar el comando de descarga.

Mientras el estado sea queued o processing, result es null. Cuando el estado sea succeeded, lee result.downloadUrl y result.expiresInSeconds. En failed o canceled, deja de consultar y revisa error.code y error.message en vez de intentar una descarga.

Consulta cada pocos segundos y respeta el límite de lectura de la cuenta. Una nueva consulta de estado puede renovar un enlace de descarga caducado mientras el archivo siga accesible. Los enlaces duran hasta 15 minutos y nunca extienden el acceso al archivo más allá de 24 horas. Consultar, descargar y repetir exactamente la solicitud idempotente no gastan créditos.

Las solicitudes de creación JSON usan sourceUrl y options. El servidor solo recupera URL HTTPS, valida cada redirección, bloquea redes privadas y aplica los mismos límites de tamaño que las subidas.

Si un sitio web bloquea CORS en el navegador, la importación local por URL puede fallar. La importación REST por URL sigue siendo un trabajo en la nube y usa tu clave API, créditos, límites de velocidad y reglas de retención.

GET /api/v1/usage devuelve { usage }. El objeto usage incluye active pool, limit, used, reserved, remaining, resetAt, windowStart y windowEnd. Las solicitudes de creación Free están limitadas a 10 rpm, las de Developer a 60 rpm, y las lecturas de estado o uso a 120 rpm por cuenta.

Las ventanas Free API se reinician por mes calendario UTC. Las ventanas Developer se reinician mensualmente en el ancla de la suscripción, incluidas las suscripciones anuales. Los créditos no se acumulan. Las cuentas Free pueden tener 2 trabajos sin terminar, las Developer 20, y la cola gratuita puede contener 100 trabajos. Un trabajo gratuito que espera más de 10 minutos se termina y libera su reserva.

El endpoint MCP es Streamable HTTP en /api/mcp. Expone compress_gif, get_compression y get_usage, y usa la misma clave API que REST.

MCP acepta URL GIF HTTPS remotas. Los archivos locales deben subirse por REST; no pases rutas locales del servidor ni cargas Base64 grandes a la herramienta MCP.

Llama a compress_gif con sourceUrl, un objeto options opcional y un idempotencyKey obligatorio. Después pasa el id devuelto a get_compression. El adaptador envuelve la respuesta REST en structuredContent.data; un transporte de herramienta correcto no significa que el trabajo de compresión haya terminado. Usa get_usage con un objeto vacío para revisar tu saldo.

Las entradas de hasta 5MB cuestan 1 crédito en modo calidad o tamaño y 2 créditos en modo objetivo. Las entradas de más de 5MB y hasta 20MB cuestan 2 créditos, o 4 créditos en modo objetivo. Cada intento de procesamiento tiene un presupuesto de 60 segundos y como máximo 8 candidatos codificados.

Los fallos de validación, fallos del sistema y tiempos de espera no gastan créditos del usuario. Un resultado válido que no alcance el objetivo solicitado aún gasta la cotización mostrada porque el cómputo se completó; el trabajo marca targetMet: false.

Los campos credits y cost.credits del trabajo muestran el coste cotizado, no la prueba de un débito completado. Los créditos se reservan cuando se acepta un trabajo, se liquidan en éxito y se liberan en fallo. Consulta /api/v1/usage para ver el saldo actual usado, reservado y restante.

Los códigos de error comunes incluyen API_KEY_REQUIRED, API_KEY_INVALID, INSUFFICIENT_CREDITS, FREE_API_NOT_ACTIVE, IDEMPOTENCY_CONFLICT, INPUT_TOO_LARGE, INVALID_GIF, RATE_LIMITED, TOO_MANY_OUTSTANDING_TASKS y FREE_COMPUTE_BUDGET_EXHAUSTED.

401 cubre claves API faltantes o no válidas. 402 solo es para créditos de usuario agotados. 403 cubre acceso Free API inactivo. 409 cubre conflictos de idempotencia. 413 cubre límites de tamaño de entrada en la nube. 422 cubre datos GIF u opciones no válidos. 429 cubre límites de creación/lectura y topes de trabajos sin terminar. 503 cubre presión temporal de cola o FREE_COMPUTE_BUDGET_EXHAUSTED; respeta Retry-After cuando esté presente.

La compresión local en el navegador y los trabajos de API en la nube tienen flujos de datos diferentes. Elige la herramienta del navegador cuando el GIF deba permanecer en tu dispositivo; usa REST o MCP cuando un flujo remoto necesite procesarlo.

La herramienta del navegador no sube tu GIF. Importar una URL contacta directamente el sitio que aloja esa imagen. Las solicitudes API y MCP suben un archivo o piden a nuestro servicio recuperar una URL HTTPS pública. Cloudflare aloja la aplicación, base de datos y almacenamiento de archivos. El acceso a archivos de entrada y salida de API caduca después de 24 horas; los enlaces de descarga duran hasta 15 minutos. La limpieza en segundo plano elimina archivos caducados, por lo que la eliminación física puede ocurrir más tarde. Registramos eventos técnicos de uso como éxito o fallo de compresión, tamaño de entrada y salida, estado del objetivo y descargas en logs de servicio de Cloudflare para medir fiabilidad y uso. Estos eventos excluyen nombres de archivo, URL de origen y contenido de archivos. Cloudflare también procesa datos de solicitud para entregar y proteger el servicio. Los logs de eventos de producto se conservan hasta 7 días.

Envía Authorization: Bearer YOUR_API_KEY en solicitudes de creación, estado y uso. La API también acepta el encabezado x-api-key. Las cookies de inicio de sesión de la cuenta no sustituyen a una clave API. Todas las claves de una cuenta comparten cuotas y límites.

Guarda la clave en una variable de entorno del servidor o en la configuración protegida de tu cliente de IA. No la coloques en una página web pública, repositorio o URL de imagen. Si una clave queda expuesta, revócala en los ajustes de claves API y crea un reemplazo. La herramienta gratuita del navegador no necesita clave API.

mode acepta quality, size o target y por defecto es quality. target requiere un targetBytes entero positivo, medido en bytes decimales: 100KB son 100000 y 1MB son 1000000. Para subidas multipart, coloca estos campos dentro del campo options codificado como JSON.

colors opcional acepta auto, 64, 128 o 256. lossyLevel acepta un entero de 0 a 200. width acepta un entero de 1 a 4096 y solicita redimensionado; omítelo para conservar las dimensiones originales. No se admite ninguna opción de eliminar fotogramas ni convertir formato.

Una solicitud procesa un GIF. Las entradas Free API están limitadas a 5MB y las Developer a 20MB. Ambas también requieren que cada borde sea como máximo 4096 píxeles, como máximo 1.000 fotogramas y width × height × frame count como máximo 50.000.000. Una animación corta pero muy grande puede alcanzar estos límites de seguridad antes que su límite de bytes.

Elige un Idempotency-Key nuevo para cada solicitud nueva de archivo y opciones, y conserva esa clave al reintentar después de una respuesta de red incierta. Las claves contienen de 1 a 128 caracteres ASCII imprimibles que no sean espacios. Una repetición idéntica devuelve la tarea existente; cambiar la entrada u opciones bajo la misma clave devuelve 409 IDEMPOTENCY_CONFLICT.

Para respuestas 429 o 503 temporales, respeta Retry-After cuando esté presente y aplica espera progresiva. Un 402 por falta de créditos necesita un reinicio de cuota o cambio de plan; repetir solicitudes no lo solucionará. Un 503 FREE_COMPUTE_BUDGET_EXHAUSTED pausa nuevos trabajos gratuitos hasta el reinicio mostrado, mientras los trabajos pagados y la herramienta local del navegador permanecen separados.

Un trabajo fallido sigue siendo el mismo trabajo fallido cuando se repite su clave. Revisa primero la causa y después usa una clave nueva para un intento nuevo deliberado. No crees claves nuevas en cada timeout: la primera solicitud quizá ya fue aceptada.