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": 300, "remaining": 288, "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.

2 · GET & POST /api/v1/credits

Solde et consommation. Plans : Free = Studio uniquement · Indie 300 · Studio 2000 attaches API/MCP / mois, remise à zéro mensuelle.

# solde
curl -H "X-API-Key: gf_..." https://gripforge.ai/api/v1/credits
→ { "ok": true, "plan": "indie", "used": 12, "limit": 300, "remaining": 288, "period": "2026-08" }

# 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

3 · 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 ; activez un plan payant pour l'API/MCP)
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

4 · Codes d'erreur

5 · Voir aussi