BeeMatra · De la photo au matériau PBR sans couture

Authentification

Tous les endpoints exigent un token Bearer dans l'en-tête HTTP. Absent ou invalide : HTTP 401 :

Authorization: Bearer bmk_xxxxxxxxxxxxxxxx

Les clés API sont générées dans Compte → Clés API. La clé en clair n'est affichée qu'une fois. Jusqu'à 5 clés actives par compte, révocables à tout moment.

⚠️ L'API ouverte est réservée aux abonnés actifs. Les tâches ne sont consultables que par leur créateur (404 pour celles d'autrui).

Créer une tâche

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

Téléchargez une photo de matériau pour créer une tâche de génération. 1 crédit est débité à l'acceptation ; un task_id est renvoyé pour le suivi.

Paramètres

Nom	Type	Description
image	file	Fichier image du matériau (formulaire multipart), ≤20 Mo, JPEG / PNG / WebP. Au choix entre image et image_url — image a la priorité si les deux sont fournis
image_url	string	URL http(s) publique de l'image (corps JSON), ≤20 Mo

Exemples de requête

cURL · téléversement multipart direct (recommandé)

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

cURL · JSON avec URL d'image

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())

Réponse

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

▸ 1 crédit débité à l'acceptation ; les tâches échouées sont remboursées intégralement.
▸ Le pré-traitement (rotation EXIF, normalisation du grand côté à 1536 px) est automatique.
▸ Images complètes uniquement — masques / recadrages à préparer par l'appelant avant l'envoi.

Consulter la progression

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

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

Interrogez le statut et la progression de la tâche. Les formats chemin et requête sont équivalents. En-tête d'authentification requis.

Réponse (en cours)

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

Réponse (terminée — voir Textures livrées pour les champs)

{ "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" } }

Nom	Type	Description
status	string	running / succeeded / failed (les tâches échouées sont remboursées automatiquement)
progress	integer	0-100
stage_label	string	Description lisible de l'étape en cours (pour affichage UI)
error	string\|null	Motif de l'échec lorsque status=failed
results	object\|null	Ensemble d'URL de textures lorsque status=succeeded

▸ Sondez toutes les 3-5 secondes ; arrêtez à succeeded/failed (limite 60/min).
▸ Vous ne pouvez consulter que vos propres tâches.

Consulter le solde

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

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

Renvoie le solde de crédits du compte associé à la clé.

Textures livrées

En cas de succès, results contient le jeu de textures PBR (2048 px sans couture) et les rendus de prévisualisation :

Champ	Type	Description
albedo	string	Albédo sans couture (couleur de base, sRGB)
normal	string	Normal map (OpenGL, Y+, linear)
roughness	string	Roughness map (linear)
height	string	Height / displacement map (linear)
ao	string	Carte d'occlusion ambiante (linear)
preview_sphere	string	Aperçu rendu sphère
preview_cube	string	Aperçu rendu cube

Toutes les URL sont téléchargeables directement, sans authentification. Le contenu est identique au pack « tout télécharger » du site (5 textures + 2 aperçus).

Codes d'erreur

Les erreurs renvoient un statut HTTP non-200 avec {"ok": false, "error": "code", "message": "..."}

HTTP	error	Description
401	missing_or_bad_bearer	En-tête Authorization manquant ou malformé
401	invalid_key	Clé API invalide ou révoquée
403	subscription_required	L'API ouverte nécessite un abonnement actif
400	no_image	Champ image manquant (ou erreur de téléversement)
400	bad_type	Format non pris en charge — JPEG / PNG / WebP uniquement
400	too_large	Image dépassant la limite de 20 Mo
400	bad_image_url	image_url n'est pas une adresse http(s) publique valide
400	image_download_failed	Échec du téléchargement de image_url (ou plus de 20 Mo)
400	bad_task_id	task_id manquant ou malformé
404	task_not_found	Tâche introuvable, ou n'appartenant pas au compte de cette clé
503	upstream_busy	Execution engine busy (usually near task completion) — simply poll again
429	rate_limited	Limite : 2 soumissions de tâche / 60 consultations par minute
429	queue_busy	Trop de tâches en file, réessayez shortly

Règles de crédits

Acquisition	Les nouveaux comptes reçoivent 3 crédits offerts. Les abonnements (Standard / Pro / Ultimate) apportent 100 / 500 / 1500 crédits par mois. Le pack boost ajoute instantanément 50 crédits.
Consommation	Chaque tâche Beta coûte 1 crédit, débité à la soumission ; les échecs sont remboursés intégralement. Même pool pour le site et l'API ouverte.
Validité	Les crédits sont valables 30 jours à compter de l'attribution ; les expirés sont purgés automatiquement. La consommation suit le premier expiré (FIFO).
Suivi	Compte → Détail des crédits : chaque attribution, consommation, expiration et remboursement est journalisée ; le solde égale toujours la somme des lots non expirés.

Plateforme ouverte