La API que edita tus fotos con IA

Crea una cuenta y devuelve el token de sesión listo para usar.

• Cuerpo: JSON o formulario con email, password y, si quieres, display_name.
• 201: user, token, token_type (Bearer), token_id.

curl -s -X POST "%ORIGIN%/api/auth/register.php" \
  -H "Content-Type: application/json" \
  -d '{"email":"cliente@ejemplo.com","password":"TuContraseñaSegura","display_name":"Mi app"}'

const r = await fetch("%ORIGIN%/api/auth/register.php", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "cliente@ejemplo.com",
    password: "TuContraseñaSegura",
    display_name: "Mi app"
  })
});
const data = await r.json(); // data.token → usar en Authorization

Mismo cuerpo que el registro (email, password). Respuesta idéntica en forma: token de acceso en 200.

Perfil, organización (nombre / email / estado) y quota del período actual (used_requests, max_requests, remaining, unlimited). También podés verlo en el panel de cliente.

Lista tokens del usuario (prefijo, nombre, fechas; nunca el secreto en claro). Marca el de la sesión con is_current.

Crea un token adicional para integraciones (por ejemplo una clave solo para tu servidor). Requiere Bearer válido.

• Cuerpo JSON: { "name": "Producción — servidor X" } (opcional; si lo omites se usa un nombre por defecto).
• 201: el nuevo token en texto plano (solo en esta respuesta), más token_id y token_prefix.

Revoca un token: query ?token_id= o JSON { "token_id": 12 }. Si revocás el de la sesión actual, was_current será true.

Invalida el token que envías en Authorization. Útil para “cerrar sesión” en el dispositivo actual.

Sin autenticación. Sirve para comprobar que el backend responde y para leer la lista actual de valores válidos de action en el campo actions del JSON.

Envía la foto y recibe la versión editada. El cuerpo va en multipart/form-data.

• image (archivo): PNG, JPEG o WebP. Obligatorio para todas las acciones salvo generar. Con generar es opcional: si la envías, el servidor la usa como imagen de referencia/inspiración.
• action (texto, obligatorio): uno de los valores permitidos (ver abajo).
• prompt (texto): opcional para las acciones predefinidas; obligatorio y no vacío si action es personalizado o generar.
• include_base64: envía 1 si quieres la imagen resultante también en base64 dentro del JSON.
• mask (archivo, opcional): PNG con transparencia, mismo ancho y alto en píxeles que image. Las zonas transparentes son donde la IA puede modificar; el resto se preserva. No aplica a generar.
• sync (texto): 1 fuerza procesamiento inmediato como antes (HTTP 200). Si no lo envías y la base de datos está configurada, el trabajo se encola (HTTP 202) y lo consume un worker en segundo plano.
• webhook_url (texto, opcional): URL que recibirá un POST JSON al terminar (event: matezia.process.completed o matezia.process.failed). Si no la enviás, se usa la URL de webhook de la cuenta (configurable en el panel) o, en su defecto, PROCESS_WEBHOOK_URL del servidor.
• webhook_secret (texto, opcional): si lo definís, el cuerpo JSON se firma con HMAC-SHA256 en el header X-matezIA-Signature: sha256=…. Misma cascada: request → cuenta → PROCESS_WEBHOOK_SECRET.

Acciones disponibles

Respuesta satisfactoria (200)

{
  "ok": true,
  "action": "arreglar",
  "mime": "image/png",
  "saved_path": "output/…/resultado.png",
  "image_url": "/output/…/resultado.png",
  "request_id": 42
}

image_url es la ruta pública para mostrar o descargar la imagen. request_id identifica la petición cuando el servicio lo incluye (útil para soporte o trazas internas).

Límite de uso (429)

Si el plan del usuario agotó las ediciones del período, la respuesta trae "ok": false y un objeto quota con fechas de periodo, máximo y usado, para mostrar un mensaje claro en tu interfaz.

curl -s -X POST "%ORIGIN%/api/process.php" \
  -H "Authorization: Bearer iaimg_TU_TOKEN" \
  -F "action=arreglar" \
  -F "prompt=Repair only the stain on the left wall." \
  -F "image=@/ruta/local/foto.jpg"

const form = new FormData();
form.append("action", "arreglar");
form.append("prompt", "Repair only the stain on the left wall.");
form.append("image", fileInput.files[0]); // File desde <input type="file">

const r = await fetch("%ORIGIN%/api/process.php", {
  method: "POST",
  headers: { Authorization: "Bearer " + token },
  body: form
});
const data = await r.json();
if (data.ok) window.open(data.image_url, "_blank");

Estado de una petición (sobre todo si se encoló con 202): processing, completed, fila queue y, si ya hay resultado, image_url. Misma política de Bearer que process.php cuando corresponde.