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 [email protected] \
  -F [email protected] \
  -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 [email protected] \
  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 [email protected] \
  -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":"[email protected]","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":"[email protected]","password":"********"}' \
  https://gripforge.ai/api/v1/auth

Unreal → Map Studio

L’import prépare automatiquement des textures adaptées au navigateur, avec conservation des originaux. Pour optimiser une scène existante : POST /api/v1/scenes/:id/optimize avec { "expectedRevision": 1, "idempotency_key": "optimize-map-v1" }. La réponse fournit un job persistant, puis les poids avant/après et le lien Studio. Une modification concurrente de la scène empêche son remplacement.

Exporter la map avec le MCP local et Unreal installé, puis importer les ressources dans le workspace. Les fichiers natifs .umap/.uasset ne sont pas lisibles par le serveur hébergé. Outils MCP et paramètres.

GET /api/v1/maps/import/unreal renvoie le contrat. Envoyer chaque GLB autonome ou image à POST /api/v1/maps/import/unreal/assets en binaire avec X-Asset-Filename et X-Content-Sha256 ; la réponse fournit la référence immuable de l’asset.

Puis envoyer le SceneDocument à POST /api/v1/maps/import/unreal. Authentification : X-API-Key et X-Workspace-Id. Les références doivent appartenir au workspace. Maximum : 128 Mio par fichier, 16 Mio par document d’import, 20 000 nœuds, 100 000 placements. La végétation répétée est éditable par groupe.

{
  "schema": "gripforge.unreal-studio-import.v1",
  "idempotency_key": "unreal-map-v1",
  "source": {
    "engine": "unreal",
    "level": "/Game/Environment/Maps/MainMap",
    "sha256": "<SHA-256 de la map source, 64 caractères hexadécimaux>",
    "warnings": ["Niagara et les shaders natifs demandent une adaptation."]
  },
  "document": "<objet SceneDocument purpose=map avec les références uploadées>"
}

→ HTTP 202 { "job_id": "gen_…", "credits": 0, "status_url": "…" }

GET /api/v1/generation-jobs/gen_…
→ result.studio_url quand status=succeeded

POST /api/v1/generation-jobs/gen_…
{ "action": "cancel" }  ou  { "action": "retry" }

Remplacer la chaîne illustrative « document » par l’objet JSON complet. L’import crée une nouvelle version de travail privée, sans remplacer une map validée. Les étapes terminées sont conservées en cas de reprise. Aucun crédit de génération ; quota de stockage habituel. Une revue visuelle dans GripForge reste nécessaire.

Creature Rig — GET & POST /api/v1/creature-rigs

Analyse anatomique du modèle depuis quatre vues, profil d’articulations modifiable, puis fabrication Blender : squelette, skinning et animations procédurales de départ. Le résultat est un nouvel asset privé à vérifier dans Character Studio. Le modèle source est conservé.

GET /api/v1/creature-rigs
POST /api/v1/creature-rigs
{ "action": "analyze", "source_id": "lib_…" }
GET /api/v1/generation-jobs/gen_…
# Inspecter result.profile et l’aperçu multivue avant fabrication
POST /api/v1/creature-rigs
{ "action": "rig", "analysis_job": "gen_…", "name": "Monstre · Rig", "reviewed_anatomy": true }
# profile : correction facultative des articulations
# reviewed_anatomy : toujours requis après contrôle du squelette
# allow_rerig : explicite si la source possède déjà des os

Session ou X-API-Key, workspace autorisé. GLB autonome de 32 Mio maximum, 200 000 sommets, 128 os. Jobs persistants, progression, annulation et reprise. Liens de sortie : Studio, GLB, source Blender, anatomie et rapport. Aucun crédit GripForge dans cette version ; Blender et un fournisseur de vision configuré sont nécessaires. La qualité visuelle et l’intégration au moteur restent à valider.

Architectural rendering — POST /api/v1/scenes/:id/realism

Profils brique, pierre, métal et verre dans le Scene Engine commun. Régions explicites sur un atlas, reflets diélectriques et profondeur d’intérieur facultative. Occlusion ambiante GTAO réglable et profils de netteté/résolution Performance, Équilibré et Qualité (jusqu’à 4K dans le renderer web). Aucun crédit de génération ; les assets sources et la version validée restent inchangés.

GET /api/v1/scenes/schema  # realism : contrat, limites et exemples
POST /api/v1/scenes/scn_…/realism
{ "expectedRevision": 4,
  "assignments": [{ "nodeId": "subject", "material": "Facade",
    "surface": { "preset": "brick", "detail": 0.2, "weathering": 0.08, "regions": [] } }],
  "ambientOcclusion": { "enabled": true, "radius": 0.4, "intensity": 0.55, "quality": "medium" }
}

Session ou X-API-Key, workspace autorisé. La réponse contient studio_url. Le bouton « Comparer le rendu » désactive temporairement le module à caméra identique. surface:null retire un traitement, ambientOcclusion:null retire l’occlusion. quality accepte les champs preset, resolutionScale et sharpness ; quality:null restaure le budget de rendu d’origine. Les zones min/max utilisent les coordonnées normalisées du maillage avant ses transformations ; elles ne sont pas détectées automatiquement. Les intérieurs simulés ne sont pas visitables. Ces shaders personnalisés ne sont pas encore reproduits par les exports natifs.

Modular vehicles — /api/v1/vehicles

Workflow recommandé : recipe.workflow = body_wheels. Concept validé → cinq vues de carrosserie sans roues (face, gauche, arrière, droite, dessus) et une roue → génération détaillée Tripo → revue de géométrie dans GripForge → retopologie → seconde revue → textures PBR multivues → assemblage et rig Blender préservant les normales. La vue du dessus reste une référence de contrôle ; Tripo utilise les quatre vues cardinales.

stage=plan chiffre séparément concept, references, geometry, topology et build. Chaque étape payante exige son budget. Les étapes geometry et topology renvoient une scène et un review_request à transmettre à gripforge_scene_review. Une revue approuvée avec preuves dans le renderer GripForge est obligatoire avant la réduction puis le texturage ; un résultat technique seul ne suffit pas. parts.body.topology conserve la révision exacte à texturer. Les étapes terminées sont conservées après interruption. parts.body.geometry accepte un GLB détaillé Hunyuan ou Blender à retopologiser/texturer ; parts.body.source et parts.wheel.source réutilisent des modèles finis. Le worker Hunyuan 2.1 actuel ne prend qu’une image : ce n’est pas le service 3.1 multivue de la vidéo.

Sorties : scène de revue GripForge, GLB animé, FBX riggé, source Blend et mesures pour Chaos Vehicles. Vérifier les cinq vues, les passages de roues, pivots, matériaux et le comportement dans le moteur cible. L’import et les Blueprints UE ne sont pas automatiques. Cette voie garde les portières fermées ; le workflow modular_doors ci-dessous gère leur articulation.

Concept commun, carrosserie, habitacle, portières et roues séparés. Réutilisation des pièces Library, instances indépendantes, pivots et animations GLB. Un véhicule existant peut aussi être segmenté par Tripo puis préparé dans Blender. Jobs persistants avec annulation et reprise des étapes terminées ; aucun remplacement automatique du modèle source.

GET /api/v1/vehicles  # contrat complet et limites
POST /api/v1/vehicles
{ "stage": "plan", "recipe": { "prompt": "Realistic silver hatchback", "doors": 4 } }
# stage=concept : master uniquement ; stage=build : pièces et assemblage.
# budget={credits:N} ou {usd:N} selon le devis ; idempotency_key requis pour reprendre.

POST /api/v1/vehicles/segment
{ "stage": "plan", "source": { "assetId": "lib_…", "revisionId": "r1" } }
# Après lecture du devis : stage=build, budget et idempotency_key.
# Le rapport liste les vrais noms des maillages et les textures conservées.
POST /api/v1/vehicles/prepare
{ "source": { "assetId": "lib_segmented", "revisionId": "r1" },
  "parts": { "Door_FL": ["door_left"], "Door_FR": ["door_right"] },
  "yaw": 0, "length": 4.4, "openAngle": 65 }
# Corps entier orienté +Z avant, +Y haut ; pivots facultatifs en mètres.
GET /api/v1/generation-jobs/gen_…
# Résultat : GLB, source Blender, rapport et studio_url pour revue animée.
# Module Web vehicle.doors : ouverture/fermeture sur entrée/sortie.

MCP : gripforge_vehicle_schema, gripforge_generate_vehicle, gripforge_vehicle_segment et gripforge_prepare_vehicle. Session ou X-API-Key, workspace autorisé. Le découpage Tripo ne garantit pas des portières fonctionnelles : contrôler la séparation, les textures, les raccords et l’habitacle dans le renderer GripForge. Blender prépare les pivots des pièces explicitement identifiées. Pour un maillage fusionné, cuts accepte des profils convexes explicites : role, outline en [avant Z, hauteur Y] et depth [proche, loin] depuis le centre du véhicule, en mètres normalisés. La découpe interpole les UV ; le contour doit être mesuré et revu. Les clips sont portables, mais la chorégraphie d’entrée du personnage et les adaptateurs de gameplay natifs restent à réaliser.

Buildings / districts — GET & POST /api/v1/architecture

Plan gratuit → concepts dans le workspace → revue → fabrication Meshy avec matériaux PBR. Les vues alternatives partent du même master. Devis séparés pour les images et la 3D ; assets Library et instances distincts dans le Scene Engine commun. Jobs persistants avec reprise des étapes terminées.

GET /api/v1/architecture
POST /api/v1/architecture
{
  "kind": "building",
  "stage": "plan",
  "recipe": {
    "id": "coffee", "name": "Coffee house",
    "prompt": "Red brick coffee shop with apartments and recessed windows",
    "style": "realistic", "floors": 4,
    "dimensions": { "width": 11, "depth": 10, "height": 15 }
  }
}
# Concepts : concept_provider="openai" (default) or "xai".
# First concept_presentation="scene"; then "isolated" + concept_reference.
# Isolated views: concept_views=["front_right","front_left","rear_right"].
# Accepter le budget de plan.concept_quote pour les images uniquement.
# Après revue : recipe.concept ou recipe.concepts=[références immuables], puis plan.
# meshQuality={geometry:"2k",texture:"4k"} : Ultra + PBR 4K conservé.
# Puis stage=build avec la recipe choisie et une idempotency_key.
# budget: {credits:N} ou {usd:N} selon plan.quote.funding.
# HTTP 202 → job_id, status_url, studio_url
GET /api/v1/generation-jobs/gen_…
# kind=district : recipe={name,buildings:[…],repetitions,streetWidth,sidewalkWidth,gap}
# concept ou source : référence {assetId,revisionId,fileRole?} du workspace.

Chaque modèle est fabriqué une fois ; les répétitions créent des instances sans nouveau coût Meshy. Progression, annulation et reprise persistantes. Résultats privés en version de travail, à vérifier dans le renderer GripForge. Dimensions ajustées sans déformation ; étages et orientation restent des objectifs visuels. Pas d’intérieurs, collisions, navigation ni remplacement automatique du jeu. Sans textures de sol fournies, route et trottoirs utilisent des matériaux unis.

Abilities / skills — GET & POST /api/v1/abilities

combat.abilities utilise le combat web existant et exporte les compétences vers Three.js, Godot, Unity et Unreal. Le contrat commun décrit les coûts, cooldowns, conditions, zones de frappe, phases et événements animation/VFX/audio.

GET /api/v1/abilities
# POST : session ou X-API-Key, JSON, 0 crédit
{ "action": "example", "model_asset": "lib_…" }
{ "action": "validate", "pack": { ... } }
{ "action": "export", "target": "all", "pack": { ... } }
# target: threejs | godot | unity | unreal | all
# réponse export: deliveries[].engine + files[].path/content

Le GET public fournit le schéma et un exemple complet. Le POST valide et exporte les fichiers sans modifier le projet moteur. Pour conserver un pack dans un workspace, installer le module Game Kit puis configurer config.pack. Les adaptateurs natifs se raccordent au combat du jeu ; les rigs, animations et VFX restent des assets à fournir. Validation incorrecte : 400 ; authentification absente : 401 ; corps supérieur à 512 Kio : 413.

7 · Codes d'erreur

8 · Voir aussi