Démarrage rapide

Récupérer un PNG directement sur disque

curl -X POST https://hytaleicon.com/api/v1/icons \
  -H "X-API-Key: hig_live_xxxxxxxxxxxx.yyyyyyyy" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "size=128" \
  -o sword_icon.png

Récupérer du JSON avec les métadonnées

curl -X POST https://hytaleicon.com/api/v1/icons \
  -H "X-API-Key: hig_live_xxxxxxxxxxxx.yyyyyyyy" \
  -H "Accept: application/json" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "size=128"

Authentification

Chaque requête exige une clé d'API dans l'en-tête X-API-Key. Les clés sont émises par l'opérateur du site et stockées hachées — le token en clair n'est affiché qu'une fois, à la création, et n'est pas récupérable.

Pour obtenir une clé, contacte Hylterium.

Une clé embarquée dans du JavaScript navigateur est publique par construction. En production, appelle l'API depuis ton propre backend et garde la clé côté serveur.

Paramètres

Noms identiques en multipart/form-data et en mode JSON. Contrairement au site, l'API refuse les valeurs hors plage au lieu de les ramener silencieusement dans les bornes.

Nom	Type	Plage	Défaut	Description
`model`	fichier / objet	obligatoire	`—`	Le fichier .blockymodel. En mode JSON : l'objet lui-même ou une chaîne base64.
`texture`	fichier / base64	obligatoire	`—`	La texture PNG. Un préfixe data:image/png;base64, est accepté.
`size`	entier	16 – 512	`64`	Taille de sortie en pixels (carré).
`supersample`	entier	1 – 8	`2`	Facteur d'antialiasing. size x supersample doit rester sous 1024.
`yaw`	flottant	-180.0 – 180.0	`-75.0`	Angle horizontal de la caméra, en degrés.
`pitch`	flottant	-90.0 – 90.0	`25.0`	Angle vertical de la caméra, en degrés.
`padding`	flottant	0.3 – 1.0	`0.92`	Fraction de l'image occupée par le modèle.
`transparent`	booléen	true / false	`true`	Fond transparent. Ignoré si background est fourni.
`background`	chaîne	#RRGGBB ou #RRGGBBAA	`—`	Couleur de fond explicite. Prime sur transparent.
`shading`	booléen	true / false	`false`	Ombrage par face (dessus clair, dessous sombre).
`center`	booléen	true / false	`true`	Recentre la silhouette visible dans l'image.
`format`	chaîne	png / json	`png`	Format de réponse. Accept: application/json a le même effet.
`disposition`	chaîne	inline / attachment	`inline`	Content-Disposition en mode PNG.
`filename`	chaîne	—	`icon.png`	Nom de base du fichier retourné.

Réponses

Par défaut le corps de la réponse est le PNG brut, avec les métadonnées en en-têtes :

HTTP/1.1 200 OK
Content-Type: image/png
Content-Disposition: inline; filename="sword_icon.png"
X-Icon-Width: 128
X-Icon-Height: 128
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-Quota-Limit: 1000
X-Quota-Remaining: 941
X-Request-Id: a1b2c3d4e5f6

Avec format=json ou Accept: application/json :

{
  "image": "iVBORw0KGgo...",
  "encoding": "base64",
  "mime_type": "image/png",
  "filename": "sword_icon.png",
  "width": 128,
  "height": 128,
  "bytes": 1837,
  "options": { "size": 128, "supersample": 2, "yaw": -75.0, "pitch": 25.0 },
  "model": { "cubes": 12, "faces": 41 },
  "rate_limit": { "limit": 10, "remaining": 9, "reset": 18 },
  "quota": { "limit": 1000, "remaining": 941, "reset": "2026-08-14T00:00:00+00:00" },
  "request_id": "a1b2c3d4e5f6"
}

Erreurs

Les erreurs sont toujours en JSON, quel que soit le format demandé. Chacune porte un code stable et un request_id à citer en cas de problème.

{
  "error": {
    "code": "invalid_parameter",
    "message": "size must be between 16 and 512, got 9999",
    "field": "size",
    "request_id": "a1b2c3d4e5f6"
  }
}

Code	HTTP	Signification
`malformed_request`	400	Le corps de la requête n'a pas pu être analysé.
`missing_api_key`	401	Aucun en-tête X-API-Key n'a été envoyé.
`invalid_api_key`	401	La clé est inconnue ou le secret ne correspond pas.
`key_revoked`	403	Cette clé a été révoquée.
`parameter_exceeds_key_limit`	403	La valeur dépasse le plafond autorisé pour votre clé.
`not_found`	404	Cet endpoint d'API n'existe pas.
`method_not_allowed`	405	Mauvaise méthode HTTP pour cet endpoint.
`payload_too_large`	413	La requête, le modèle ou la texture dépasse la taille maximale.
`unsupported_media_type`	415	Envoyez du multipart/form-data ou du application/json.
`missing_field`	422	Un champ obligatoire (model ou texture) est absent.
`invalid_parameter`	422	Un paramètre est illisible ou hors plage.
`invalid_model`	422	Le modèle n'est pas du JSON BlockyModel valide.
`model_has_no_geometry`	422	Le modèle est valide mais ne contient aucun cube visible.
`model_too_complex`	422	Le modèle contient trop de cubes pour être rendu.
`invalid_texture`	422	La texture n'a pas pu être décodée comme image.
`texture_too_large`	422	La texture dépasse les dimensions maximales.
`render_too_large`	422	size x supersample dépasse le budget autorisé.
`rate_limited`	429	Trop de requêtes. Attendez avant de réessayer.
`quota_exceeded`	429	Quota journalier épuisé. Remise à zéro à minuit UTC.
`internal_error`	500	Erreur serveur inattendue. Citez le request_id en le signalant.

Limites de débit et quotas

Deux limites s'appliquent : une réserve de rafale par clé qui se recharge en continu, et un quota journalier remis à zéro à minuit UTC. Les requêtes en échec sont remboursées — seuls les rendus réussis sont décomptés du quota.

Limite	Valeur
`size`	16 – 512
`supersample`	1 – 8
`size × supersample`	≤ 1024
`model`	≤ 2 MiB
`texture`	≤ 4 MiB, 4096 × 4096 px
request	≤ 8 MiB
cubes	≤ 5000

Chaque réponse porte l'état courant :

X-RateLimit-Limit        10
X-RateLimit-Remaining    9
X-RateLimit-Reset        18
X-Quota-Limit            1000
X-Quota-Remaining        941
X-Quota-Reset            2026-08-14T00:00:00+00:00
Retry-After              12        # 429 only

CORS

Tous les endpoints /api/v1 envoient Access-Control-Allow-Origin: * et exposent les en-têtes de limite, pour qu'un client navigateur puisse lire son propre budget et temporiser correctement.

Schéma OpenAPI

Le schéma complet lisible par machine est disponible à https://hytaleicon.com/api/v1/openapi.json

API du générateur d'icônes