REST API

API reference

Une seule opération centrale : attacher un prop à un personnage riggé et récupérer un bind prêt pour votre moteur. Authentification par clé API — créez un compte pour obtenir la vôtre. 1 crédit = 1 attache réussie ; sans clé, l'API tourne en mode local non compté (développement).

1 · POST /api/v1/attach

Corps multipart/form-data. Header X-API-Key optionnel (requis en production, décompte 1 crédit).

Exemple :

curl -X POST https://gripforge.ai/api/v1/attach \
  -H "X-API-Key: gf_..." \
  -F character=@hero.glb \
  -F prop=@sword.glb \
  -F style=melee \
  -F hand=right

Réponse :

{
  "bind": {
    "bone": "R_Hand",
    "boneAliases": ["R_Hand"],
    "style": "melee",
    "hand": "right",
    "heightRatio": 0.44,
    "bodyHeight": 1.80,
    "position": [0.014, 0.062, -0.008],
    "rotation": [1.5708, 0, -0.2618],
    "rotationOrder": "XYZ",
    "space": "bone-local",
    "baseQuat": [0.05, 0.69, 0.11, 0.70],
    "handRig": "wrist-only",
    "gripPose": [],
    "notes": ["..."]
  },
  "confidence": 0.66,
  "exports": { "json": "...", "three": "...", "unity": "...", "godot": "..." },
  "credits": { "plan": "indie", "used": 12, "limit": 100, "remaining": 88, "period": "2026-08" }
}

bind est en espace local de l'os (space: bone-local) ; les snippets exports.three / unity / godot sont prêts à coller. GET sur le même endpoint renvoie cette référence en JSON. Une attache réussie écrit le bind (et le GLB armé si export=glb) dans Library — ce n'est pas un second crédit. Réponse : library.id +library.file_url (URL signée, même origine).

2 · Library — GET/POST /api/v1/library

Casier du compte : persos, props, textures, binds, VFX. Même session ou X-API-Key que l'attach. Pas une marketplace. Quotas : Free 200 Mo · pack 100/500 = 2 Go · pack 1 500 = 20 Go.

# lister
curl -H "X-API-Key: gf_..." https://gripforge.ai/api/v1/library
# envoyer
curl -X POST -H "X-API-Key: gf_..." \
  -F kind=character -F name=Hero -F file=@hero.glb \
  https://gripforge.ai/api/v1/library
# attacher par ids
curl -X POST -H "X-API-Key: gf_..." \
  -F character_id=lib_... -F prop_id=lib_... -F export=glb \
  https://gripforge.ai/api/v1/attach
# fichier signé
GET /api/v1/library/:id
GET /api/v1/library/:id/file?exp=&sig=
PATCH /api/v1/library/:id   { "name": "…" }
DELETE /api/v1/library/:id
DELETE /api/v1/library      { "ids": ["lib_…", "lib_…"] }
# bulk delete is workspace-only; community items you do not own are skipped

3 · POST /api/v1/textures/prep

Préparer une texture de jeu (terrain, props) : raccord 50 % + fondu des coutures, agrandissement lanczos fidèle. Pas de modèle génératif. Même auth session / X-API-Key. Aucun crédit consommé.

curl -X POST https://gripforge.ai/api/v1/textures/prep \
  -H "X-API-Key: gf_..." \
  -F file=@rock.png \
  -F seamless=1 \
  -F scale=4 \
  -F size=2048 \
  -F save=1

# ou JSON : texture_id / image_url
# → { id, urls: { albedo }, library_id, width, height }

4 · GET /api/v1/shaders · GET /api/v1/shaders/:id · POST /api/v1/shaders/pull

Catalogue shaders (miroir autorisé de GodotShaders.com). Même auth session / X-API-Key que l'attach. Liste { id, name, engines } — engines godot | unity | three. L'alias slash_reveal pointe le crescent slash 2D. Browser : /studio/shaders et onglet Shaders de Library. Le détail renvoie les sources traduites + params. v1 : le pull est gratuit (inclus dans un plan attach, 0 crédit — un pull métré serait 1 crédit = 1 pull). L'API hébergée renvoie le contenu des fichiers ; le MCP npm gripforge_shader_pull les écrit dans out_dir.

# liste
curl -H "X-API-Key: gf_..." "https://gripforge.ai/api/v1/shaders?q=slash_reveal"
# détail (sources + params)
curl -H "X-API-Key: gf_..." https://gripforge.ai/api/v1/shaders/slash_reveal
# pull Godot → fichiers + snippet ShaderMaterial
curl -X POST -H "X-API-Key: gf_..." -H "content-type: application/json" \
  -d '{"id":"slash_reveal","engine":"godot","out_dir":"./shaders"}' \
  https://gripforge.ai/api/v1/shaders/pull

5 · GET & POST /api/v1/credits

Solde et consommation. Free = 15 Studio + 3 essais API/MCP / mois. Packs one-shot (100 / 500 / 1 500) — les crédits achetés n'expirent pas.

# solde
curl -H "X-API-Key: gf_..." https://gripforge.ai/api/v1/credits
→ { "ok": true, "plan": "indie", "used": 3, "limit": 115, "remaining": 112, "purchased": 100, "period": "2026-09" }

# consommer manuellement (utilisé par le serveur MCP)
curl -X POST -H "X-API-Key: gf_..." -H "content-type: application/json" \
  -d '{"action":"charge"}' https://gripforge.ai/api/v1/credits

6 · POST /api/v1/auth

Comptes email + mot de passe. L'inscription crée la clé API (plan Free). Session par cookie httpOnly — utilisée par la page compte, pas nécessaire pour appeler l'API (la clé suffit).

# inscription (crée la clé API ; un pack de crédits débloque API/MCP au-delà de l'essai)
curl -X POST -H "content-type: application/json" \
  -d '{"action":"signup","email":"vous@studio.dev","password":"********"}' \
  https://gripforge.ai/api/v1/auth

# connexion → cookie de session httpOnly gf_session
curl -X POST -H "content-type: application/json" \
  -d '{"action":"login","email":"vous@studio.dev","password":"********"}' \
  https://gripforge.ai/api/v1/auth

7 · Codes d'erreur

8 · Voir aussi