← Retour à l'atelier

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.

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

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 ÷ 256 Ko/s), et le débit doit rester d'au moins 32 Ko/s. Vérifiez la connexion, puis réessayez.
409 not_ready SVG demandé trop tôt : sondez jusqu'à done.
410 gone Résultat 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 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.