Crear comparación Subir imágenes API

API de gatos.pics

Todo lo que hace el sitio también se hace desde un script: publicar comparaciones, subir capturas y actualizar páginas. Sin cuentas. Funciona sin llave con un límite por hora; con una llave API personal no hay límite.

Empieza aquí

Una comparación publicada es una página con su propio enlace, https://gatos.pics/p/<token>/. Se crea con un pedido, y la llave que recibes al crearla te deja cambiarla o borrarla después.

  1. Elige cómo publicar. Lo más fácil es el script listo: una carpeta por versión y te devuelve el enlace. Si prefieres armar el pedido tú, un solo curl alcanza.
  2. Publica. La respuesta trae url (el enlace para compartir), token (el código de la página) y delete_key (la llave de la página).
  3. Guarda la llave de la página. Con ella se actualiza y se borra la página. Se muestra una sola vez y no se puede recuperar.

¿Qué quieres hacer?

Publicar una comparación desde carpetas de capturasScript listo
Publicar con un solo pedido, desde curl o tu propio scriptPublicar una comparación
Cambiar una página que ya publiqué: quitar o sumar versiones, quitar cuadrosActualizar una página
Leer los resultados de la prueba ciegaPrueba ciega
Mi script ya sube a slow.picsCompatible con slow.pics
Subir capturas sueltas desde Upload Assistant, upbrr o ShareXCapturas sueltas (ShareX)
Poner un botón de subida en mi foro o trackerBotón de subida
Sin scripts, desde el navegadorCrear comparación · Subir imágenes

Llaves

Hay dos llaves, y ninguna es obligatoria para publicar.

LlaveQué esEncabezado
Llave de la página (delete_key)Nace con cada página y sirve solo para esa página: actualizarla, borrarla, cambiar su imagen compartida y leer sus resultados. Viene en la respuesta al publicar, una sola vez; no se puede recuperar.x-delete-key
Llave API (empieza con gk_)Personal y opcional: pídela a quien administra gatos.pics. Quita el límite por hora, y también actualiza y lee las páginas que publicaste con ella. No borra: para borrar hace falta la llave de la página.x-api-key
  • Sin llave, publicar y subir funcionan igual, con un límite por hora.
  • Al publicar o subir, una llave API mal escrita responde 401; no pasa al modo sin llave. Para publicar sin llave, quita el encabezado.
  • Upload Assistant, upbrr y ShareX mandan la llave API en Authorization.
  • Todo error llega como JSON, {"error": "el motivo"}, en español; con el encabezado accept-language: en, en inglés.

Guías

Publicar una comparación

POSThttps://gatos.pics/api/comparison · formulario multipart con archivos normales (nada de base64).

curl -H "x-api-key: TU_LLAVE" \
  -F title="Mi peli · fuente vs encodes" \
  -F "Fuente=@fuente_01.png" -F "Fuente=@fuente_02.png" \
  -F "x265=@x265_01.png"     -F "x265=@x265_02.png" \
  https://gatos.pics/api/comparison
  • Cada campo es una versión y su nombre es el nombre de la versión. La primera es la referencia (queda a la izquierda).
  • Los cuadros salen del orden por nombre: la primera imagen de cada versión es el cuadro 1, la segunda el 2… Todas las versiones llevan la misma cantidad.
  • Opcional: title y frames="136259,140021", el número de cada cuadro (si no, 1, 2, 3…).
  • Opcional: métricas y datos de cada versión, y los ajustes de la prueba ciega.
  • Sin llave también funciona: quita la línea -H "x-api-key: …".

Respuesta 201:

{ "url": "https://gatos.pics/p/Ab3…/", "token": "Ab3…",
  "delete_key": "…", "delete_url": "https://gatos.pics/api/page/Ab3…" }

Guarda delete_key, la llave de la página: con ella la actualizas y la borras.

Script listo: carpetas → enlace

Descarga gatos_comp.py (solo Python 3, nada que instalar). Una carpeta por versión, las capturas en orden de nombre; los .json de métricas al lado se suben solos, y un info.json en la carpeta lleva los datos de esa versión.

Descargar gatos_comp.py
python3 gatos_comp.py --title "Mi peli" fuente/ x265/ av1/
# → https://gatos.pics/p/Ab3…/   (la llave de la página queda en gatos_comp.txt)

La llave API, si tienes, va en la variable GATOS_API_KEY. Las páginas grandes se suben imagen por imagen, sin tope de 300 MiB por pedido. El nombre de cada carpeta es el nombre de la versión.

Actualizar una página publicada

Una página publicada se puede cambiar sin que cambie su enlace: quitar versiones o cuadros, sumar o reemplazar una versión, cambiar el título. Es un PATCH a /api/page/<token> con la llave de la página. Solo viaja lo que cambia; lo demás queda como estaba.

  • En los ejemplos, cambia TOKEN por el código de tu página y LLAVE_DE_LA_PAGINA por su delete_key.
  • El campo "format": "gatos.pics/cmp@1" va siempre.
  • Todo o nada: si el pedido se rechaza, la página queda exactamente como estaba.
  • Quien ya abrió la página ve el cambio al recargarla.

Los ids de versiones y cuadros

Los cambios nombran cada versión y cada cuadro por su id. Los ids de una página están en su manifiesto, que es público:

curl https://gatos.pics/p/TOKEN/manifest.json
{ "title": "Mi peli", "frames": ["1", "2", "3"],
  "variants": [ { "id": "Fuente", "name": "Fuente" },
                { "id": "x265", "name": "x265" },
                { "id": "AV1-CRF-30", "name": "AV1 CRF 30" } ] }
  • Id de versión: sale del nombre del campo (/api/comparison) o de la carpeta (gatos_comp.py). Se quitan los acentos y todo lo que no sea letra, número, _ o - se vuelve -; hasta 28 caracteres. «AV1 CRF 30» queda AV1-CRF-30. Mayúsculas y minúsculas cuentan.
  • Id de cuadro: 1, 2, 3… en orden; si publicaste con frames="136259,140021", esos números.
  • Una imagen se nombra <id de versión>_<id de cuadro>: x265_2 es el cuadro 2 de x265.

Quedarte con la fuente y el encode ganador

remove quita versiones enteras, con sus imágenes. manifest.frames es la lista de cuadros que quedan. Los dos pueden ir en el mismo pedido:

curl -X PATCH -H "x-delete-key: LLAVE_DE_LA_PAGINA" -H "content-type: application/json" \
  -d '{"format": "gatos.pics/cmp@1", "remove": ["x265"], "manifest": {"frames": ["1", "2"]}}' \
  https://gatos.pics/api/page/TOKEN

Respuesta 200: {"url": "…", "token": "…", "title": "…", "version": 2}. La página debe quedar con al menos 2 versiones.

Quitar solo cuadros

Nombra en manifest.frames los cuadros que se quedan, en el orden en que se verán. Los que no nombres se borran de todas las versiones.

curl -X PATCH -H "x-delete-key: LLAVE_DE_LA_PAGINA" -H "content-type: application/json" \
  -d '{"format": "gatos.pics/cmp@1", "manifest": {"frames": ["1", "3"]}}' \
  https://gatos.pics/api/page/TOKEN

Cambiar el título

curl -X PATCH -H "x-delete-key: LLAVE_DE_LA_PAGINA" -H "content-type: application/json" \
  -d '{"format": "gatos.pics/cmp@1", "manifest": {"title": "Mi peli: el encode final"}}' \
  https://gatos.pics/api/page/TOKEN

Sumar o reemplazar una versión

La versión va en manifest.variants y sus imágenes en images, en base64. Si su id ya existe en la página, la reemplaza; si no, se suma al final. Hace falta una imagen por cada cuadro de la página, del mismo tamaño en píxeles que las demás. Este script (solo Python 3) suma una carpeta de PNG:

import base64, json, pathlib, urllib.request

PAGINA  = "https://gatos.pics/p/TOKEN/"
LLAVE   = "LLAVE_DE_LA_PAGINA"
CARPETA = "av1-crf28"   # sus PNG en orden de nombre, uno por cuadro
VERSION = {"id": "av1-crf28", "name": "AV1 CRF 28"}

cuadros = json.load(urllib.request.urlopen(PAGINA + "manifest.json"))["frames"]
archivos = sorted(pathlib.Path(CARPETA).glob("*.png"))
assert len(archivos) == len(cuadros), "hace falta una imagen por cuadro"
imagenes = {VERSION["id"] + "_" + c: "data:image/png;base64," + base64.b64encode(a.read_bytes()).decode()
            for c, a in zip(cuadros, archivos)}
parche = {"format": "gatos.pics/cmp@1", "manifest": {"variants": [VERSION]}, "images": imagenes}
pedido = urllib.request.Request(PAGINA.replace("/p/", "/api/page/").rstrip("/"), json.dumps(parche).encode(), method="PATCH",
                                headers={"x-delete-key": LLAVE, "content-type": "application/json"})
print(urllib.request.urlopen(pedido).read().decode())
  • Al reemplazar una versión se guarda el objeto que mandas, entero: lo que no traiga (nombre, métricas) se pierde.
  • Para cambiar solo algunas imágenes de una versión, manda solo esas en images.
  • Una versión con imágenes nuevas empieza de cero en la prueba ciega; las demás conservan sus resultados.
  • Desde el navegador, lo mismo es Compartir → Añadir una versión… en la página.

Páginas grandes: actualizar en partes

Un pedido lleva hasta 300 MiB de imágenes. Para reemplazar una página más grande sin que nadie la vea a medias, las partes arman una copia pendiente y la página cambia una sola vez, con la última parte:

# 1. la primera parte: un .cmp completo con los primeros cuadros  →  202 {"pending": "ID", …}
curl -X PUT -H "x-delete-key: LLAVE_DE_LA_PAGINA" -H "content-type: application/json" \
  --data-binary @parte1.cmp "https://gatos.pics/api/page/TOKEN?pending=start"
# 2. las siguientes: un PATCH con los cuadros que se suman  →  202
curl -X PATCH -H "x-delete-key: LLAVE_DE_LA_PAGINA" -H "content-type: application/json" \
  --data-binary @parte2.json "https://gatos.pics/api/page/TOKEN?pending=ID"
# 3. la última publica todo  →  200
curl -X PATCH -H "x-delete-key: LLAVE_DE_LA_PAGINA" -H "content-type: application/json" \
  --data-binary @parte3.json "https://gatos.pics/api/page/TOKEN?pending=ID&commit=1"
  • Cada PATCH nombra en manifest.frames todos los cuadros que la copia lleva hasta ahí, y trae las imágenes de los nuevos.
  • Una copia pendiente se descarta sola tras 2 horas sin recibir partes, y a las 24 horas en cualquier caso.
  • Para reemplazar de una vez una página que cabe en un pedido: PUT /api/page/<token> con un .cmp completo. Mismo enlace, misma llave.

Si algo falla

El servidor diceQué pasó
403Se necesita la llave API o la llave de esta página para actualizarla.Falta x-delete-key, o esa llave es de otra página.
404no existeEl código de la página está mal escrito, o la página se borró.
409esta página ya se está actualizando; espera a que termineHay otro cambio en curso sobre la misma página.
413la página resultante pesaría … MiB y el tope por página es 1024 MiBCon el cambio, la página pasaría de 1 GiB.
422format no soportado (se espera gatos.pics/cmp@1)Falta el campo format.
422variants: la página debe quedar con al menos 2 variantesQuitaste demasiadas: una página tiene de 2 a 12 versiones.
422remove: la variante "x264" no existe en la páginaEse id no está en la página: revisa manifest.json.
422Faltan imágenes tras unir el parche (2): av1_3, av1_4A una versión le falta la imagen de algún cuadro.
422imagen "av1_1": mide 1280x720 y la página 1920x1080; todas las imágenes deben tener las mismas dimensionesLas imágenes nuevas no miden lo mismo que las de la página.

Borrar una página

curl -X DELETE -H "x-delete-key: LLAVE_DE_LA_PAGINA" https://gatos.pics/api/page/TOKEN

Borra la página, sus imágenes y su imagen compartida; responde {"ok": true}. No se puede deshacer, y solo lo hace la llave de la página.

Métricas y datos de cada versión

  • Opcional: métricas. Un .json con el mismo nombre que una imagen: {"ssimulacra2": 81.4, "butteraugli": 0.92, "cvvdp": 9.61, "vmaf": 97.2}. Cualquier nombre de métrica sirve; las conocidas se muestran con su nombre y si más alto o más bajo es mejor.
  • Nombres de métricas: los que quieras. Se guardan en minúsculas, con letras, números y _ (espacios y símbolos se vuelven _, hasta 32 caracteres); el valor es un número o un texto corto de hasta 40 caracteres ("frame_type": "B"); hasta 16 por imagen. Las que la página no conoce salen tal cual, sin marcar en verde la mejor (no sabe si más alto o más bajo es mejor).
  • Opcional: datos de la versión. Un info.json en el campo de una versión (-F "x265=@info.json") describe la versión entera: {"profile": "dark", "tonemap": "bt2390"}. Hasta 12 datos, cada uno un número o un texto de hasta 80 caracteres; salen en la misma tarjeta que las métricas.
curl -F "Fuente=@fuente_01.png" -F "x265=@x265_01.png" \
  -F "x265=@x265_01.json" -F "x265=@info.json" \
  https://gatos.pics/api/comparison

Resultados de la prueba ciega

Toda página ofrece una prueba ciega a quien la visita. La tabla completa es solo para quien publicó, con la llave de la página o su llave API:

curl -H "x-delete-key: LLAVE_DE_LA_PAGINA" https://gatos.pics/api/page/TOKEN/standings
  • versions: por versión, ganadas, empates, perdidas, comparaciones (picks) y puntuación (score). head_to_head: cada par. per_frame: por cuadro, cómo le fue a cada versión contra la referencia.
  • ?ref=<id> elige la referencia de per_frame; si no, es la de la prueba, src o la primera versión.
  • La respuesta trae ETag: si la mandas de vuelta en If-None-Match y nada cambió, llega un 304 sin cuerpo.

Ajustes al publicar

Campos opcionales de POST /api/comparison:

  • ref=<versión>: la referencia de la prueba ciega (el nombre de su campo). La mitad de las comparaciones son contra ella; ref_share=0.75 lo cambia a tres de cada cuatro.
  • requester=1: la respuesta trae requester_url, un segundo enlace para votar, privado, para quien pidió la comparación. Sus resultados cuentan con los de todos y también aparte: /standings?voters=requester.
  • request_id=<id>: un texto tuyo (hasta 64 letras, números o . _ : -) que /standings devuelve.
  • En un .cmp, la referencia va en el manifiesto: "blind": {"ref": "src", "ref_share": 0.75}.

Capturas sueltas (ShareX)

Upload Assistant y upbrr traen un host de imágenes llamado sharex al que se le puede cambiar la dirección. Apúntalo a gatos.pics con tu llave API y tus capturas se suben aquí.

Upload Assistant: en la sección DEFAULT de tu config.py:

"img_host_1": "sharex",
"sharex_url": "https://gatos.pics/api/sharex",
"sharex_api_key": "tu-llave-api",

upbrr: en Ajustes, elige el host de imágenes ShareX, con URL https://gatos.pics/api/sharex y como API key tu llave API.

Cualquier cliente ShareX sirve igual: un archivo por pedido en el campo file, la llave en Authorization; la respuesta trae link. Varias imágenes en un pedido: POST /api/drop con {"name", "images": {"archivo.png": "data:image/png;base64,…"}}.

Borrado automático: agrega "expires": "P1W" a POST /api/drop. Plazos: PT5M, PT15M, PT30M, PT1H, PT3H, PT6H, PT12H, P1D a P6D, P1W a P3W, P1M a P6M. Un mes son 30 días.

Traer por URL: agrega "urls": ["https://…/foto.png"] a POST /api/drop y el servidor trae hasta 12 imágenes. Solo direcciones públicas, por los puertos 80 y 443, y con los mismos topes de una subida normal. GET /api/drop dice si está disponible.

Algunos trackers solo aceptan capturas de sus propios hosts aprobados; en esos, la herramienta usará el siguiente host de tu lista.

Botón de subida para foros y trackers

https://gatos.pics/upload funciona como el botón de imgbb: tu sitio abre la página en una ventana y, al terminar la subida, el BBCode llega solo a tu cuadro de texto.

UNIT3D: cambia una línea de resources/js/vendor/imgbb.js y vuelve a generar los assets:

url: 'https://gatos.pics/upload',
  • Es el mismo protocolo del plugin de imgbb: cualquier sitio que ya lo use solo cambia esa dirección.
  • Llega un [url=…][img]…[/img][/url] por imagen, uno por línea.
  • La ventana sigue abierta después de insertar para que guardes la llave de borrado, que nunca sale de ella.
  • Se aplican los límites de la subida sin llave.

Compatible con slow.pics

Si tu script de comparación sube a slow.pics y te deja cambiar la dirección, cambia https://slow.pics por https://gatos.pics. Los mismos pasos funcionan:

GET  /comparison                 # el script lo pide primero (cookie XSRF-TOKEN fija, igual para todos)
POST /upload/comparison          # collectionName, comparisons[i].name, comparisons[i].imageNames[j]
POST /upload/image/<id>         # una vez por imagen: collectionUuid, imageUuid, file
     → https://gatos.pics/c/<key>   # lleva a la página
  • Cada comparisons[i] es un cuadro y cada imageNames[j] una versión. /upload/collection (una sola versión) crea una galería como Subir imágenes.
  • Se ignoran: hentai, public, tags, tmdbId, removeAfter, optimizeImages (los PNG siempre se reempacan sin pérdida) y el inicio de sesión de slow.pics.
  • La respuesta de /upload/comparison trae además url y delete_key, que los scripts de slow.pics ignoran.
  • Extra de gatos.pics en /upload/comparison: info[j], un JSON con los datos de la versión j (el orden de imageNames).
  • Una comparación que no recibe todas sus imágenes en 1 hora se descarta.
  • Para subir sin límite, agrega el encabezado x-api-key.

Formato .cmp

Lo que guarda el creador: un JSON con el manifiesto y las imágenes en base64. Sirve para todo lo que no cubre /api/comparison: colores, notas, cuadros con nombre, versiones parciales.

{ "format": "gatos.pics/cmp@1",
  "manifest": { "title": "Mi peli", "frames": ["1", "2"],
                "variants": [ { "id": "src", "name": "Fuente" }, { "id": "x265", "name": "x265" } ] },
  "images": { "src_1": "data:image/png;base64,…", "src_2": "data:image/png;base64,…",
              "x265_1": "data:image/png;base64,…", "x265_2": "data:image/png;base64,…" } }
curl -X POST -H "content-type: application/json" --data-binary @comparacion.cmp https://gatos.pics/api/upload
  • La respuesta es la misma de /api/comparison. Con ese mismo archivo, PUT /api/page/<token> reemplaza una página ya publicada.
  • Todos los campos, en docs/formato-cmp.md del repositorio.
  • En format vale "gatos.pics/cmp@1" o su forma corta "cmp@1", al publicar y al actualizar.
  • Imagen compartida: una página publicada por la API nace sin ella y /s/<token>.png lleva a su primera imagen. Súbela con curl -X POST -H "content-type: image/png" -H "x-delete-key: <llave>" --data-binary @vista.png https://gatos.pics/api/shot/<token>, o deja que tools/share_image.cjs del repositorio dibuje la del visor y la suba.
  • Que la dibuje el servicio: el mismo pedido con el cuerpo vacío (curl -X POST -H "x-delete-key: <llave>" https://gatos.pics/api/shot/<token>) dibuja la vista inicial del botón «Compartir»: las dos primeras versiones partidas al medio, con sus nombres y métricas. Solo con imágenes PNG.
  • Todas las imágenes de una página en un .zip: https://gatos.pics/z/<token>.zip.

Referencia

Todas las direcciones

Todas cuelgan de https://gatos.pics. Una respuesta que no empieza con 2 trae {"error": "…"}. Los errores que cualquier subida puede dar:

401La llave API que enviaste no es correcta.
403Falta la llave que ese pedido necesita, o publicar sin llave está cerrado por ahora.
413El pedido o la página pasan del tamaño permitido.
422Algo del pedido no sirve; el mensaje dice qué.
429Demasiados pedidos sin llave desde tu conexión: espera un rato o usa una llave API.
503 · 507El servidor está ocupado o sin espacio: reintenta más tarde.

POST/api/comparison

LlaveOpcional: x-api-key.
Cuerpomultipart/form-data. Un campo por versión con sus imágenes; opcionales title, frames, ref, ref_share, requester, request_id, los .json de métricas y un info.json por versión.
Respuesta201 con url, token, delete_key, delete_url, title y share_image_upload; además requester_url, request_id y ref si los pediste.
GuíaPublicar una comparación

POST/api/upload

LlaveOpcional: x-api-key.
CuerpoJSON: un .cmp completo.
Respuesta201 con url, token, delete_key, delete_url, title y share_image_upload.
GuíaFormato .cmp

PUT/api/page/<token>

Llavex-delete-key, o x-api-key si publicaste la página con esa llave.
CuerpoJSON: un .cmp completo, que reemplaza la página. Con ?pending=start empieza una actualización en partes.
Respuesta200 con url, token, title y version. En partes, 202 con pending, parts y expires.
Errores403 la llave no es de esta página · 404 no existe · 409 ya se está actualizando · 413 · 422
GuíaPáginas grandes: actualizar en partes

PATCH/api/page/<token>

Llavex-delete-key, o x-api-key si publicaste la página con esa llave.
CuerpoJSON con format y solo lo que cambia: manifest (title, frames, frame_labels, variants, blind), images y remove. Con ?pending=<id> suma una parte; con &commit=1, la última.
Respuesta200 con url, token, title y version. En partes, 202 con pending, parts y expires.
Errores403 la llave no es de esta página · 404 no existe · 409 ya se está actualizando · 413 · 422
GuíaActualizar una página publicada

DELETE/api/page/<token>

Llavex-delete-key. La llave API no borra.
Respuesta200 {"ok": true}
Errores403 llave incorrecta · 404 no existe · 409 la página se está actualizando

GET/api/page/<token>/standings

Llavex-delete-key, o x-api-key si publicaste la página con esa llave.
Opciones?ref=<id>, ?voters=requester, encabezado If-None-Match.
Respuesta200 con token, request_id, ballots, versions, head_to_head, per_frame y blind; o 304.
Errores401 falta la llave · 403 la llave no es de esta página · 404 no existe · 422 ref o voters no válidos
GuíaResultados de la prueba ciega

POST/api/shot/<token>

Llavex-delete-key.
CuerpoUn PNG (content-type: image/png), hasta 16 MiB y 8000 píxeles por lado: la imagen compartida de la página.
Respuesta201 {"url": "https://gatos.pics/s/<token>.png"}

POST/api/drop

LlaveOpcional: x-api-key.
CuerpoJSON: images ({"archivo.png": "data:image/png;base64,…"}); opcionales name, expires y urls.
Respuesta201 con token, delete_key, delete_url e images: por imagen, url, bbcode, markdown y html.
AdemásGET /api/drop da los límites vigentes sin llave. DELETE /api/drop/<token> con x-delete-key borra la subida.
GuíaCapturas sueltas (ShareX)

POST/api/sharex

LlaveTu llave API en Authorization.
Cuerpomultipart/form-data con una imagen en el campo file.
Respuesta201, la misma de /api/drop, más link: la dirección de la imagen.
AdemásGET /api/sharex da los valores para configurar la herramienta.

Compatibles con slow.pics

GET /comparison, POST /upload/comparison, POST /upload/collection, POST /upload/image/<id> y GET /c/<key>: ver Compatible con slow.pics.

Para leer, sin llave

/p/<token>/La página.
/p/<token>/manifest.jsonSu manifiesto: título, cuadros, versiones y sus ids.
/s/<token>.pngSu imagen compartida; si no tiene, lleva a su primera imagen.
/z/<token>.zipTodas sus imágenes en un .zip.
/d/<token>/<archivo>Una imagen de una subida suelta; en el navegador, su galería.
/d/<token>.zipTodas las imágenes de una subida suelta.
/uploadLa página del botón de subida.

Límites

Sin llaveCon llave API
Comparaciones5 por hora por conexiónsin límite por hora
Por imagen25 MiB25 MiB
Por pedido300 MiB300 MiB
Por página1 GiB (1024 MiB), 12 versiones, 200 cuadrosigual
Capturas sueltaslos valores vigentes están en GET /api/drop25 MiB por imagen, 300 imágenes y 300 MiB por pedido

No hace falta comprimir tus capturas: el servidor reoptimiza los PNG sin pérdida (píxeles idénticos, menos peso).