Referencia de la API — PhotoRestore

Beta privada

Estos endpoints están activos en esta vista previa pero aún no son públicos — todavía no se emiten claves de API y la forma puede cambiar antes de una versión estable.

Únete a la lista de espera de la API

Descripción general

Esta app expone una pequeña API de tareas del mismo origen: sube una imagen, envía una tarea de restauración o escalado y luego consulta su resultado. Todavía no hay claves de API — cada solicitud está delimitada por la cookie de sesión de invitado de tu navegador.

URL base: /apiTodas las rutas a continuación son relativas a esta base del mismo origen — no hay un host de API independiente que configurar.
Autenticación: Con ámbito de sesión mediante una cookie httpOnly emitida al continuar como invitado. Todavía no existen claves de API (consulta "Planeado" abajo).

Garantía del contrato: el result_url de una tarea siempre es un image_url válido — puedes enviarlo directamente a /api/restore o /api/upscale para encadenar otra operación (así es exactamente como funciona "Escalar esta imagen" después de una restauración).

POST/api/uploads

Subir una imagen

Sube un único archivo de imagen y devuelve una URL de recurso del mismo origen que puedes pasar como image_url a Restaurar o Escalar.

Cuerpo de la solicitud

Nombre	Tipo	Obligatorio	Límites	Descripción
file	binary (multipart/form-data)	Sí	—	El archivo de imagen, enviado como multipart/form-data.

Cuerpo de la respuesta

Nombre	Tipo	Obligatorio	Límites	Descripción
image_url	string	Sí	—	Una URL de recurso del mismo origen devuelta por una subida previa — la única forma de image_url aceptada.
bytes	number	Sí	0–9007199254740991	El tamaño del archivo almacenado, en bytes.
mime	string	Sí	—	El tipo MIME detectado del archivo almacenado (autoritativo — no el tipo declarado por el cliente).

Ejemplo de respuesta 201

{
  "image_url": "/api/mock-assets/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "bytes": 2458112,
  "mime": "image/jpeg"
}

Ejemplos de código

curl -X POST 'https://your-app.example.com/api/uploads' \
  -F "file=@photo.jpg"

POST/api/restore

Crear una tarea de restauración

Inicia una tarea de restauración asíncrona para una imagen subida previamente. Devuelve de inmediato una referencia de tarea en estado pending — consulta el progreso con GET /api/jobs/{job_id}.

Cuerpo de la solicitud

Nombre	Tipo	Obligatorio	Límites	Descripción
image_url	string	Sí	/api/mock-assets/<uuid>	Una URL de recurso del mismo origen devuelta por una subida previa — la única forma de image_url aceptada.
user_hint	string	No	max 300 chars	Una nota de texto libre opcional que describe la foto, usada para orientar el paso de análisis simulado.
params.colorize	boolean	Sí	—	Obligatorio por compatibilidad de esquema. El valor se acepta, pero no selecciona un modo de procesamiento: la restauración es idéntica sea cual sea el valor.
params.resolution	unknown	Sí	—
params.variant	unknown	Sí	—

Cuerpo de la respuesta

Nombre	Tipo	Obligatorio	Límites	Descripción
job_id	string	Sí	job_<uuid>	El identificador único de esta tarea.
status	pending \| processing \| succeeded \| failed \| cancelled	Sí	—	El estado actual del ciclo de vida de la tarea.

Ejemplo de respuesta 202

{
  "job_id": "job_3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "pending"
}

Ejemplos de código

curl -X POST 'https://your-app.example.com/api/restore' \
  -H 'Content-Type: application/json' \
  -d '{  "image_url": "/api/mock-assets/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",  "user_hint": "the sky was blue",  "params": {    "colorize": true  }}'

POST/api/upscale

Crear una tarea de escalado

Inicia una tarea de escalado asíncrona para una imagen subida previamente, con el modo y la resolución objetivo solicitados. Devuelve de inmediato una referencia de tarea en estado pending.

Cuerpo de la solicitud

Nombre	Tipo	Obligatorio	Límites	Descripción
image_url	string	Sí	/api/mock-assets/<uuid>	Una URL de recurso del mismo origen devuelta por una subida previa — la única forma de image_url aceptada.
user_hint	string	No	max 300 chars	Una nota de texto libre opcional que describe la foto, usada para orientar el paso de análisis simulado.
params.mode	fast \| balanced \| high	Sí	—	El equilibrio entre calidad y velocidad del escalado.
params.target_megapixels	number	Sí	1–64	La resolución de salida deseada, en megapíxeles.

Cuerpo de la respuesta

Nombre	Tipo	Obligatorio	Límites	Descripción
job_id	string	Sí	job_<uuid>	El identificador único de esta tarea.
status	pending \| processing \| succeeded \| failed \| cancelled	Sí	—	El estado actual del ciclo de vida de la tarea.

Ejemplo de respuesta 202

{
  "job_id": "job_3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "pending"
}

Ejemplos de código

curl -X POST 'https://your-app.example.com/api/upscale' \
  -H 'Content-Type: application/json' \
  -d '{  "image_url": "/api/mock-assets/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",  "params": {    "mode": "fast",    "target_megapixels": 12  }}'

GET/api/jobs/{job_id}

Obtener el estado de la tarea

Devuelve el estado actual de una tarea: status, progress y — una vez succeeded — un result_url que puedes descargar o reenviar como un nuevo image_url.

Cuerpo de la respuesta

Nombre	Tipo	Obligatorio	Límites	Descripción
job_id	string	Sí	job_<uuid>	El identificador único de esta tarea.
type	restore \| upscale	Sí	—	Qué herramienta creó esta tarea.
status	pending \| processing \| succeeded \| failed \| cancelled	Sí	—	El estado actual del ciclo de vida de la tarea.
progress	number	Sí	0–100	Porcentaje completado, de 0 a 100.
result_url	string	No	—	Presente una vez que la tarea tiene éxito — una URL de recurso del mismo origen que también puede enviarse como un nuevo image_url.
result_urls.light	string	Sí	—
result_urls.strong	string	No	—
before_url	string	No	—
error.code	INVALID_REQUEST \| UNSUPPORTED_FORMAT \| FILE_TOO_LARGE \| JOB_NOT_FOUND \| VLM_FAILED \| WORKFLOW_FAILED \| TIMEOUT \| CANCELLED \| INTERNAL \| INSUFFICIENT_CREDITS \| STORAGE_QUOTA_EXCEEDED	Sí	—	El motivo del fallo legible por máquina.
error.message	string	Sí	—	Un mensaje de fallo legible para humanos. Presente solo cuando status es failed.
created_at	string	Sí	—	Cuándo se creó la tarea, en formato ISO 8601.
updated_at	string	Sí	—	Cuándo se actualizó la tarea por última vez, en formato ISO 8601.

Ejemplo de respuesta 200

{
  "job_id": "job_3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "restore",
  "status": "succeeded",
  "progress": 100,
  "result_url": "/api/mock-assets/6c1d3a2e-4f5b-4a1e-9c2d-1a2b3c4d5e6f",
  "created_at": "2026-08-03T10:15:00.000Z",
  "updated_at": "2026-08-03T10:15:42.000Z"
}

Ejemplos de código

curl -X GET 'https://your-app.example.com/api/jobs/job_3fa85f64-5717-4562-b3fc-2c963f66afa6'

POST/api/jobs/{job_id}/cancel

Cancelar una tarea

Solicita la cancelación de una tarea. Cancelar una tarea que ya está en un estado terminal no tiene efecto y devuelve su estado actual sin cambios.

Cuerpo de la respuesta

Nombre	Tipo	Obligatorio	Límites	Descripción
job_id	string	Sí	job_<uuid>	El identificador único de esta tarea.
status	pending \| processing \| succeeded \| failed \| cancelled	Sí	—	El estado actual del ciclo de vida de la tarea.

Ejemplo de respuesta 202

{
  "job_id": "job_3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "cancelled"
}

Ejemplos de código

curl -X POST 'https://your-app.example.com/api/jobs/job_3fa85f64-5717-4562-b3fc-2c963f66afa6/cancel'

Ciclo de vida del estado de la tarea

Cada tarea pasa por esta máquina de estados. pending y processing no son terminales; succeeded, failed y cancelled son terminales y nunca vuelven a cambiar.

pendingprocessingsucceededfailedcancelled

Si una tarea no alcanza un estado terminal dentro del plazo de consulta del cliente, se trata como un fallo TIMEOUT.

Códigos de error

Todos los errores usan este conjunto fijo de códigos. INVALID_REQUEST, UNSUPPORTED_FORMAT, FILE_TOO_LARGE y JOB_NOT_FOUND se devuelven como respuestas de error HTTP; el resto aparece como error.code dentro de un objeto de tarea una vez que esa tarea alcanza un estado terminal failed o cancelled.

Código	Dónde aparece	Significado
INVALID_REQUEST	Respuesta de error HTTP 400	Esta solicitud no es válida. Verifica tu información e inténtalo de nuevo.
UNSUPPORTED_FORMAT	Respuesta de error HTTP 415	Este formato de archivo no es compatible. Usa JPEG, PNG, WebP, HEIC o HEIF.
FILE_TOO_LARGE	Respuesta de error HTTP 413	Este archivo es demasiado grande. Usa una imagen más pequeña.
JOB_NOT_FOUND	Respuesta de error HTTP 404	No pudimos encontrar este trabajo. Puede haber expirado.
VLM_FAILED	Dentro del campo error de una tarea terminal	No pudimos analizar esta imagen. Inténtalo de nuevo.
WORKFLOW_FAILED	Dentro del campo error de una tarea terminal	El procesamiento falló. Inténtalo de nuevo.
TIMEOUT	Dentro del campo error de una tarea terminal	Esto está tardando más de lo esperado. Inténtalo de nuevo.
CANCELLED	Dentro del campo error de una tarea terminal	Este trabajo fue cancelado.
INTERNAL	Respuesta de error HTTP 500	Algo salió mal de nuestro lado. Inténtalo de nuevo.
INSUFFICIENT_CREDITS	Respuesta de error HTTP 402	No tienes suficientes créditos para esta tarea. Recarga para continuar.
STORAGE_QUOTA_EXCEEDED	Respuesta de error HTTP 413	Tu álbum está lleno. Elimina fotos o mejora tu plan para continuar.

Planeado: una API pública versionada

Se planea una puerta de enlace /v1 versionada para integraciones de terceros — claves de API en lugar de cookies de sesión, webhooks al completar la tarea en lugar de sondeo, y límites de tasa por clave. Nada de esto está implementado todavía, y no se ha comprometido ninguna forma de solicitud/respuesta, esquema de autenticación, firma de webhook ni número de límite de tasa. Considera todo lo que está por encima de esta sección — las rutas /api del mismo origen que esta app realmente ofrece hoy — como el único contrato vigente. Si /v1 llega a lanzarse, se documentará por separado con una especificación completa; este párrafo es un aviso, no un adelanto.

En esta página

Descripción general

Subir una imagen

Cuerpo de la solicitud

Cuerpo de la respuesta

Ejemplo de respuesta 201

Ejemplos de código

Crear una tarea de restauración

Cuerpo de la solicitud

Cuerpo de la respuesta

Ejemplo de respuesta 202

Ejemplos de código

Crear una tarea de escalado

Cuerpo de la solicitud

Cuerpo de la respuesta

Ejemplo de respuesta 202

Ejemplos de código

Obtener el estado de la tarea

Cuerpo de la respuesta

Ejemplo de respuesta 200

Ejemplos de código

Cancelar una tarea

Cuerpo de la respuesta

Ejemplo de respuesta 202

Ejemplos de código

Ciclo de vida del estado de la tarea

Códigos de error