API et MCP

Envoyez une image PNG ou JPEG depuis un script, un plugin ou un agent IA et récupérez un SVG. L'API utilise le calcul sur le serveur de Homotope : même moteur, même file, mêmes crédits et même plafond d'image que l'atelier.

Description complète (OpenAPI 3.1) : /api/v1/openapi.json.

Le moteur est open source (MIT) : paquet @homotope/engine sur npm, sources sur GitHub.

Démarrage en 3 étapes

  1. Créez une clé dans l'atelier, « Mon compte » → « Clés d'API ». Elle commence par hmt_live_ et n'est affichée qu'une fois : gardez-la dans un gestionnaire de secrets, jamais dans un dépôt ni dans une URL.
  2. Envoyez une image : POST /api/v1/jobs répond aussitôt 202 avec l'identifiant du calcul, sans attendre la fin.
  3. Sondez puis téléchargez : interrogez GET /api/v1/jobs/{id} toutes les 2 à 5 secondes jusqu'à l'état done, puis récupérez GET /api/v1/jobs/{id}/svg, ou GET /api/v1/jobs/{id}/result?format=pdf (svg, pdf, dxf ou eps).

Exemples avec curl

La clé passe dans l'en-tête Authorization: Bearer …, et seulement là.

export HOMOTOPE_KEY="hmt_live_…"

# Vérifier la clé
curl -sS https://homotope.example/api/v1/me \
  -H "Authorization: Bearer $HOMOTOPE_KEY"

# Envoyer une image (options facultatives : préréglage, nom, réglages)
curl -sS https://homotope.example/api/v1/jobs \
  -H "Authorization: Bearer $HOMOTOPE_KEY" \
  -F [email protected] \
  -F 'options={"preset":"logo","name":"Logo","options":{"export":{"precision":2}}}'
# → 202 {"id":"…","state":"queued","links":{…}}

# Palette imposée : tracer avec VOS couleurs (2 à 64, distinctes), aucune autre n'est inventée
curl -sS https://homotope.example/api/v1/jobs \
  -H "Authorization: Bearer $HOMOTOPE_KEY" \
  -F [email protected] \
  -F 'options={"preset":"logo","palette":["#E30613","#0057B8","#FFFFFF"]}'

# Sonder jusqu'à "state": "done"
curl -sS https://homotope.example/api/v1/jobs/ID \
  -H "Authorization: Bearer $HOMOTOPE_KEY"

# Télécharger le SVG
curl -sS -o logo.svg https://homotope.example/api/v1/jobs/ID/svg \
  -H "Authorization: Bearer $HOMOTOPE_KEY"

# Le même résultat en PDF, EPS ou DXF (découpe ; tolerance : courbes aplaties, en px)
curl -sS -OJ "https://homotope.example/api/v1/jobs/ID/result?format=dxf&tolerance=0.05" \
  -H "Authorization: Bearer $HOMOTOPE_KEY"

# Séparations : une couche par couleur (SVG à calques, DXF à couches ; ZIP pour PDF et EPS)
curl -sS -OJ "https://homotope.example/api/v1/jobs/ID/result?format=svg&layers=1" \
  -H "Authorization: Bearer $HOMOTOPE_KEY"
# … ou un fichier par couleur, en ZIP
curl -sS -OJ "https://homotope.example/api/v1/jobs/ID/result?format=pdf&layers=zip" \
  -H "Authorization: Bearer $HOMOTOPE_KEY"

# Prêt pour la découpe ? Contrôle du DXF (outil de 0,3 mm, frontières communes fusionnées)
curl -sS "https://homotope.example/api/v1/jobs/ID/cutcheck?tool_mm=0.3&merge_shared=true" \
  -H "Authorization: Bearer $HOMOTOPE_KEY"
# → {"id":"…","report":{"blocking":0,"check":2,"totals":{…},"issues":[…],…}}

# Derniers calculs (20 par défaut, 100 au plus ; "nextCursor" pour la suite)
curl -sS "https://homotope.example/api/v1/jobs?limit=50" \
  -H "Authorization: Bearer $HOMOTOPE_KEY"

# Annuler un calcul en file, ou supprimer un résultat
curl -sS -X DELETE https://homotope.example/api/v1/jobs/ID \
  -H "Authorization: Bearer $HOMOTOPE_KEY"

Préréglages : logo, illustration, pixel-art, line-art, centerline (trait unique : chemins stroke d'une seule passe, pour laser, traceur ou broderie), photo. Les réglages admis et leurs bornes sont ceux du panneau « Avancé » de l'atelier, décrits dans le document OpenAPI (JobOptions).

Choisir le préréglage, recalculer la même image

POST /api/v1/suggest rend le préréglage que l'atelier propose pour l'image (mêmes règles), sa confiance, ses raisons et les préréglages qui conviennent aussi : gratuit, aucun calcul, rien d'enregistré (30 par minute et par clé). Une source : un fichier (file), ou en JSON une image_url ou le source_job_id d'un calcul du compte. Avec "preset":"auto", un calcul applique ce préréglage (comme « Appliquer » dans l'atelier) et GET /api/v1/jobs/ID le dit dans preset_suggested.

# Préréglage conseillé (gratuit)
curl -sS https://homotope.example/api/v1/suggest \
  -H "Authorization: Bearer $HOMOTOPE_KEY" -F [email protected]
# → {"preset":"logo","confidence":"high","reasons":[…],"compatible":["black-white"],"auto_preset":"logo"}

# Calculer avec le préréglage conseillé
curl -sS https://homotope.example/api/v1/jobs \
  -H "Authorization: Bearer $HOMOTOPE_KEY" -F [email protected] -F 'options={"preset":"auto"}'

# Un autre préréglage sur la MÊME image, sans la renvoyer (un nouveau calcul, compté)
curl -sS https://homotope.example/api/v1/jobs \
  -H "Authorization: Bearer $HOMOTOPE_KEY" -H "Content-Type: application/json" \
  -d '{"source_job_id":"ID","preset":"photo"}'

Un calcul reste un calcul, quelle que soit sa source. Garde contre les abus (pas un tarif) : 8 calculs au plus d'une même image (même empreinte, même compte) par heure glissante, à l'atelier comme par l'API et le MCP ; au-delà, 429 (too_many_variants) avec retry_after en secondes. Regardez le résultat avant de recalculer. La source d'un calcul est gardée 7 jours ; après, 410 (source_expired).

Formats du résultat

Prêt pour la découpe ?

GET /api/v1/jobs/{id}/cutcheck analyse le DXF que produirait …/result?format=dxf (mêmes tolerance, include_background, merge_shared), en lecture seule, et rend un rapport JSON :

Droits

Limites

Erreurs

Toute erreur a la forme {"error": {"code": "…", "message": "…"}}, message en français.

Statut Codes Que faire
401 invalid_api_key Clé absente, inconnue ou révoquée.
402 payment_required Ni quota Pro restant ni crédit : achetez un pack ou passez Pro.
404 not_found Calcul inconnu (ou d'un autre compte).
408 upload_timeout Envoi trop long ou trop lent : le délai vaut max(60 s, taille annoncée ÷ 64 Ko/s), 285 s au plus (un corps doit arriver en moins de 5 minutes), et le débit doit rester d'au moins 16 Ko/s sur 30 s glissantes, après 10 s de grâce. Le champ reason dit la cause (slow : débit, total : délai). Vérifiez la connexion, puis réessayez.
409 not_ready SVG demandé trop tôt : sondez jusqu'à done.
410 gone, source_expired Résultat, ou source d'un calcul, supprimé (rétention ou suppression).
413 payload_too_large, too_large, quota_exceeded Fichier trop lourd, image trop grande, ou stockage plein.
415 unsupported_media_type Ni PNG ni JPEG (signature du fichier, jamais son nom ni son type déclaré).
422 stacked_separations, too_complex, unconvertible Un fichier par couleur demandé sur un résultat empilé (choisissez le mode « découpé ») ; conversion ou contrôle de découpe trop long ou trop lourd (simplifiez le tracé) ; résultat non convertible. Réessayer tel quel ne sert à rien.
429 rate_limited, too_many_jobs, too_many_uploads, too_many_variants Attendez le délai de Retry-After, sans boucler.
503 busy, storage_unavailable, unavailable Places de conversion prises (busy, avec Retry-After), ou service momentanément indisponible : réessayez plus tard.

Serveur MCP (agents IA)

Homotope expose un serveur MCP (Model Context Protocol), simple façade de cette API, en transport « Streamable HTTP » :

Exemple de configuration d'un client MCP (la clé reste chez vous) :

{
  "mcpServers": {
    "homotope": {
      "type": "http",
      "url": "https://homotope.example/mcp",
      "headers": { "Authorization": "Bearer hmt_live_…" }
    }
  }
}

Outils proposés à l'agent :

Une erreur d'outil porte le statut et le code de l'API (402, 413, 429…) et un message en français. Une image_url doit être publique : https, port 443, ni adresse privée ni locale, 3 redirections au plus, lue en 15 secondes.

Pas d'OAuth : la clé d'API suffit. Pas de transport stdio : le serveur est distant. Le serveur ne garde aucune session entre deux requêtes.