BeeMatra · De la foto al material PBR sin costuras

Autenticación

Todos los endpoints requieren un token Bearer en la cabecera HTTP. Si falta o es inválido: HTTP 401:

Authorization: Bearer bmk_xxxxxxxxxxxxxxxx

Las claves de API se generan en Cuenta → Claves de API. La clave en texto claro se muestra solo una vez. Máximo 5 claves activas por cuenta, revocables en cualquier momento.

⚠️ La API abierta está disponible solo para suscriptores activos. Las tareas solo pueden consultarlas su creador (las de otros usuarios devuelven 404).

Crear tarea

POST https://beematra.net/api/v1/tasks

Sube una foto de material para crear una tarea de generación. Se cobran 1 crédito al aceptarse; se devuelve un task_id para consultar.

Parámetros

Nombre	Tipo	Descripción
image	file	Archivo de imagen del material (formulario multipart), ≤20 MB, JPEG / PNG / WebP. Usa image o image_url — image tiene prioridad si se envían ambos
image_url	string	URL http(s) pública de la imagen (cuerpo JSON), ≤20 MB

Ejemplos de solicitud

cURL · subida multipart directa (recomendado)

curl -X POST https://beematra.net/api/v1/tasks \ -H "Authorization: Bearer bmk_xxxx" \ -F "image=@/path/to/photo.jpg"

cURL · JSON con URL de imagen

curl -X POST https://beematra.net/api/v1/tasks \ -H "Authorization: Bearer bmk_xxxx" \ -H "Content-Type: application/json" \ -d '{"image_url": "https://example.com/photo.jpg"}'

Python

import requests resp = requests.post( "https://beematra.net/api/v1/tasks", headers={"Authorization": "Bearer bmk_xxxx"}, files={"image": open("photo.jpg", "rb")}, ) print(resp.json())

Respuesta

{ "ok": true, "task_id": "W20261020_170000_a1b2c3", "status": "running", "progress": 0, "status_url": "https://beematra.net/api/v1/tasks/W20261020_170000_a1b2c3", "balance": 87 }

▸ Se cobran 1 crédito al aceptarse; las tareas fallidas se reembolsan íntegramente.
▸ El preprocesamiento (rotación EXIF, normalización del lado mayor a 1536 px) es automático.
▸ Solo imágenes completas — máscaras / recortes deben preprocesarlos el llamante antes de subirlos.

Consultar progreso

GET https://beematra.net/api/v1/tasks/{task_id}

GET https://beematra.net/api/v1/tasks/?task_id={task_id}

Consulta el estado y el progreso de la tarea. Los formatos de ruta y de consulta son equivalentes. Cabecera de autenticación obligatoria.

Respuesta (en curso)

{ "ok": true, "task_id": "W20261020_170000_a1b2c3", "status": "running", "progress": 45, "stage_label": "Generating textures…", "error": null, "note": null, "results": null }

Respuesta (completada — ver Texturas entregadas para los campos)

{ "ok": true, "task_id": "W20261020_170000_a1b2c3", "status": "succeeded", "progress": 100, "stage_label": "Completed", "error": null, "note": null, "results": { "albedo": "/uploads/derived/…/seamless_albedo.png", "normal": "/uploads/derived/…/normal.png", "roughness": "/uploads/derived/…/roughness.png", "height": "/uploads/derived/…/height.png", "ao": "/uploads/derived/…/ao.png", "preview_sphere": "/uploads/derived/…/preview_sphere.png", "preview_cube": "/uploads/derived/…/preview_cube.png" } }

Nombre	Tipo	Descripción
status	string	running / succeeded / failed (las tareas fallidas se reembolsan automáticamente)
progress	integer	0-100
stage_label	string	Descripción legible de la etapa actual (para mostrar en la UI)
error	string\|null	Motivo del fallo cuando status=failed
results	object\|null	Conjunto de URLs de texturas cuando status=succeeded

▸ Sondea cada 3-5 segundos; detente en succeeded/failed (límite 60/min).
▸ Solo puedes consultar tus propias tareas.

Consultar saldo

GET https://beematra.net/api/v1/balance

curl https://beematra.net/api/v1/balance \ -H "Authorization: Bearer bmk_xxxx"

Devuelve el saldo de créditos de la cuenta vinculada a la clave.

Texturas entregadas

En caso de éxito, results contiene el conjunto de texturas PBR (2048 px sin costuras) y las vistas previas renderizadas:

Campo	Tipo	Descripción
albedo	string	Albedo sin costuras (color base, sRGB)
normal	string	Mapa de normales (OpenGL, Y+, linear)
roughness	string	Mapa de rugosidad (linear)
height	string	Mapa de altura / desplazamiento (linear)
ao	string	Mapa de oclusión ambiental (linear)
preview_sphere	string	Vista previa de esfera
preview_cube	string	Vista previa de cubo

Todas las URL se descargan directamente, sin autenticación. El contenido es idéntico al paquete «descargar todo» del sitio (5 texturas + 2 vistas previas).

Códigos de error

Los errores devuelven un estado HTTP distinto de 200 con {"ok": false, "error": "código", "message": "descripción"}

HTTP	error	Descripción
401	missing_or_bad_bearer	Cabecera Authorization ausente o malformada
401	invalid_key	Clave de API inválida o revocada
403	subscription_required	La API abierta requiere una suscripción activa
400	no_image	Falta el campo image (o error de subida)
400	bad_type	Formato no admitido — solo JPEG / PNG / WebP
400	too_large	La imagen supera el límite de 20 MB
400	bad_image_url	image_url no es una dirección http(s) pública válida
400	image_download_failed	Error al descargar image_url (o superior a 20 MB)
400	bad_task_id	task_id ausente o malformado
404	task_not_found	Tarea no encontrada, o no pertenece a la cuenta de esta clave
503	upstream_busy	Execution engine busy (usually near task completion) — simply poll again
429	rate_limited	Límite: 2 envíos de tareas / 60 consultas por minuto
429	queue_busy	Demasiadas tareas en cola, reintenta en breve

Reglas de créditos

Obtención	Las cuentas nuevas reciben 3 créditos gratis. Las suscripciones (Standard / Pro / Ultimate) entregan 100 / 500 / 1500 créditos al mes. El paquete extra añade 50 créditos al instante.
Consumo	Cada tarea Beta cuesta 1 crédito, cobrado al enviarse; los fallos se reembolsan íntegramente. El mismo pool para la web y la API abierta.
Validez	Los créditos son válidos durante 30 días desde su concesión; los expirados se depuran automáticamente. El consumo sigue el lote que expira primero (FIFO).
Seguimiento	Cuenta → Detalle de créditos: cada concesión, consumo, expiración y reembolso queda registrado; el saldo siempre equivale a la suma de los lotes no expirados.

Plataforma abierta