Tâches et résultats

Soumettez des tâches asynchrones en toute sécurité avec l’idempotence, envoyez des médias, suivez l’état et téléchargez les résultats.

Soumettre une tâche (asynchrone)

Il n’y a pas d’appel synchrone. POST /api/v1/jobs valide l’entrée, réserve le prix sur vos crédits et répond immédiatement : 202 pour une nouvelle tâche, 200 lorsqu’une nouvelle tentative idempotente correspond à une précédente.

En-tête	Valeur	Remarques
`Authorization`	`Bearer <API key>`	Ou envoyez la clé dans x-api-key.
`Content-Type`	`application/json`
`Idempotency-Key`	`<unique string ≤128>`	Obligatoire. Ne le réutilisez que pour retenter la même requête.

Champ	Type	Obligatoire	Remarques
`model`	`string`	obligatoire	Slug du modèle dans le catalogue.
`input`	`object`	obligatoire	Champs du schéma d’entrée du modèle.
`expectedPriceMicros`	`integer`	facultatif	Prix que vous avez affiché à l’utilisateur. En cas d’écart, 409 PRICE_CHANGED est renvoyé avant tout débit.

Réessayer en toute sécurité

Conservez la même Idempotency-Key et le même corps lors d’une nouvelle tentative après une panne réseau. Utilisez une nouvelle clé si l’entrée change. Réutiliser une clé avec une entrée modifiée renvoie 409 IDEMPOTENCY_CONFLICT.

Importer des médias

Les champs image et vidéo acceptent une URL HTTPS publique ou une référence media:<uuid>. Importez d’abord les fichiers locaux :

POST /api/v1/media

curl -X POST https://api.hermes-ai.net/api/v1/media \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  -H "Content-Type: image/png" \
  --data-binary @input.png
# → { "reference": "media:<uuid>", ... }  Use the reference in an image or video field.

Obtenir les résultats de la tâche

Interrogez GET /api/v1/jobs/{id} toutes les quelques secondes et arrêtez-vous à un statut final. Ne resoumettez pas automatiquement une tâche reconciliation_required.

Statut	Final	Signification
`queued`	non	Acceptée, en attente d’un worker.
`submitting`	non	En cours d’envoi au fournisseur du modèle.
`running`	non	Le modèle est en cours de génération.
`succeeded`	oui	Terminée. Les résultats sont dans assets.
`failed`	oui	Terminée sans résultat. La réservation est libérée.
`reconciliation_required`	oui	The result is being verified. Keep the task ID and do not resubmit automatically.

Champ	Type	Remarques
`id`	`string`	ID de tâche Hermes AI. Utilisez-le pour interroger.
`model`	`string`	Slug du modèle.
`status`	`string`	Voir les statuts de tâche.
`errorCode`	`string \| null`	Défini lorsqu’une tâche échoue ou doit être examinée.
`priceMicros`	`integer`	Devis fixé à l’admission, en micro-unités USD.
`currency`	`"USD"`
`createdAt / updatedAt`	`string`	Horodatages ISO 8601.
`assets[]`	`array`	{ id, type, url?, text? }. url est un lien /api/v1/results/<uuid> de même origine.
`replayed`	`boolean`	Soumission uniquement. true lorsqu’une nouvelle tentative idempotente correspond.

Les ressources du résultat contiennent du texte ou une URL /api/v1/results/<uuid> de même origine. Téléchargez les fichiers avec les mêmes identifiants (portée media:read). GET /api/v1/jobs liste vos 100 dernières tâches.