Black Forest LabsVérification

FLUX 3 / Text to Image

flux-3-text-to-image

texte vers imageSortie: ImageEntrée: texte

Chargement du prix…

Prix catalogue officiel · Non vérifié

Essayer dans le Playground Obtenir une clé d’API

Paramètres

Obligatoire

promptprompt: string

Scene description or edit instruction. No negative prompt; a bbox JSON array may be appended for layout or local edits. 1–20000 chars

resolutionresolution: string

Resolution tier, decides the price. 768sq ~768x768, 1k ~1MP, 1.5k ~2MP, 2k ~4MP, 4k ~16MP.

Options courantes

aspectRatioaspectRatio: string

Output aspect ratio. auto follows the first reference image when editing, or the prompt for text-to-image.

Avancé (2)

groundinggrounding: boolean

Allow web or image search before generation. On by default.

safetyTolerancesafetyTolerance: integer

Moderation tolerance, 0 strictest to 4, default 2. 0–4

Aperçu de la requête

{
  "model": "flux-3-text-to-image",
  "input": {
    "aspectRatio": "1:1",
    "resolution": "1k",
    "grounding": true,
    "safetyTolerance": 2
  }
}

Le playground web envoie ce corps avec votre session connectée. Depuis votre code, envoyez le même corps avec une clé d’API.

Montant estimé

Chargement du prix…

Les crédits sont réservés à l’acceptation d’une tâche et débités seulement en cas de succès. Une tâche échouée libère la réservation ; un résultat non confirmé reste réservé jusqu’à vérification.

Ce qu’il fait

Generate images from a text prompt.

Resolution-based pricing · up to 4K

Paramètres d’entrée

Uniquement les champs acceptés par ce modèle. Les champs obligatoires doivent être fournis.

Champ	Type	Obligatoire	Par défaut	Valeurs autorisées et contraintes
`prompt`	`string`	obligatoire	—	Scene description or edit instruction. No negative prompt; a bbox JSON array may be appended for layout or local edits. 1–20000 chars
`aspectRatio`	`string`	facultatif	`"1:1"`	Output aspect ratio. auto follows the first reference image when editing, or the prompt for text-to-image. Parmi: `"auto"`, `"21:9"`, `"2:1"`, `"16:9"`, `"3:2"`, `"7:5"`, `"4:3"`, `"5:4"`, `"1:1"`, `"4:5"`, `"3:4"`, `"5:7"`, `"2:3"`, `"9:16"`, `"1:2"`, `"9:21"`
`resolution`	`string`	obligatoire	`"1k"`	Resolution tier, decides the price. 768sq ~768x768, 1k ~1MP, 1.5k ~2MP, 2k ~4MP, 4k ~16MP. Parmi: `"768sq"`, `"1k"`, `"1.5k"`, `"2k"`, `"4k"`
`grounding`	`boolean`	facultatif	`true`	Allow web or image search before generation. On by default.
`safetyTolerance`	`integer`	facultatif	`2`	Moderation tolerance, 0 strictest to 4, default 2. 0–4

Limites et comportement

Asynchrone uniquement : soumettez une tâche, puis interrogez le résultat.
prompt: 1–20000 chars
safetyTolerance: 0–4

Point de terminaison

Tous les modèles partagent une API de tâches asynchrone. Ce modèle est sélectionné par son slug.

Soumettre

POST https://api.hermes-ai.net/api/v1/jobs

{
  "model": "flux-3-text-to-image",
  "input": {
    "prompt": "A lighthouse on a rocky coast at sunrise, soft light",
    "resolution": "1k"
  }
}

Puis interrogez GET /api/v1/jobs/{id} jusqu’à ce que le statut soit final.

Authentification

Envoyez une clé d’API avec la portée jobs:create pour soumettre et jobs:read pour interroger.

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.

Corps de la 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.

champs input

Les champs inconnus sont rejetés avec INVALID_MODEL_INPUT.

Champ	Type	Obligatoire	Par défaut	Valeurs autorisées et contraintes
`prompt`	`string`	obligatoire	—	Scene description or edit instruction. No negative prompt; a bbox JSON array may be appended for layout or local edits. 1–20000 chars
`aspectRatio`	`string`	facultatif	`"1:1"`	Output aspect ratio. auto follows the first reference image when editing, or the prompt for text-to-image. Parmi: `"auto"`, `"21:9"`, `"2:1"`, `"16:9"`, `"3:2"`, `"7:5"`, `"4:3"`, `"5:4"`, `"1:1"`, `"4:5"`, `"3:4"`, `"5:7"`, `"2:3"`, `"9:16"`, `"1:2"`, `"9:21"`
`resolution`	`string`	obligatoire	`"1k"`	Resolution tier, decides the price. 768sq ~768x768, 1k ~1MP, 1.5k ~2MP, 2k ~4MP, 4k ~16MP. Parmi: `"768sq"`, `"1k"`, `"1.5k"`, `"2k"`, `"4k"`
`grounding`	`boolean`	facultatif	`true`	Allow web or image search before generation. On by default.
`safetyTolerance`	`integer`	facultatif	`2`	Moderation tolerance, 0 strictest to 4, default 2. 0–4

Réponse

202 pour une nouvelle tâche, 200 lorsqu’une relecture avec Idempotency-Key correspond. GET /api/v1/jobs/{id} renvoie la même structure sans replayed.

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.

Statuts de tâche

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.

Erreurs

Chaque corps d’erreur est { code, error }. Traitez-les selon code.

HTTP	Code	Signification et action
`401`	`AUTH_REQUIRED`	Clé d’API ou session manquante ou invalide.
`403`	`INSUFFICIENT_SCOPE`	La clé d’API n’a pas la portée requise par ce point de terminaison.
`403`	`PERMISSION_DENIED`	Cet identifiant ne peut pas effectuer cette opération.
`429`	`API_KEY_RATE_LIMITED`	La limite de débit de la clé d’API est atteinte. Respectez Retry-After.
`429`	`API_KEY_USAGE_EXCEEDED`	La clé d’API a atteint sa limite d’utilisation. Créez une nouvelle clé.
`400`	`INVALID_REQUEST`	Le corps n’est pas un objet JSON ou une valeur obligatoire manque.
`400`	`INVALID_IDEMPOTENCY_KEY`	Idempotency-Key doit comporter de 1 à 128 caractères ASCII imprimables.
`400`	`INVALID_MODEL_INPUT`	input ne correspond pas au schéma du modèle (champ inconnu, champ obligatoire manquant ou valeur invalide).
`400 / 413`	`INPUT_TOO_LARGE`	Le corps de la requête dépasse 256 Ko. Importez d’abord les médias et envoyez une référence média.
`404`	`REQUEST_NOT_FOUND`	No chat request with this ID belongs to your account.
`404`	`MODEL_NOT_FOUND`	Aucun modèle n’a ce slug.
`404`	`JOB_NOT_FOUND`	Aucune tâche avec cet ID n’appartient à votre compte.
`409`	`IDEMPOTENCY_CONFLICT`	Cette Idempotency-Key a été utilisée avec une autre entrée. Utilisez une nouvelle clé pour une nouvelle requête.
`409`	`PRICE_CHANGED`	Le prix diffère de expectedPriceMicros. Récupérez le prix et confirmez à nouveau.
`409`	`MODEL_PRICE_UNAVAILABLE`	Aucun prix n’est encore configuré pour ce modèle ; il ne peut donc pas s’exécuter.
`409`	`PAYMENT_REVIEW_REQUIRED`	A refund left an uncovered balance. Contact support or cover the balance before submitting tasks.
`409`	`INSUFFICIENT_CREDITS`	Les crédits disponibles ne couvrent pas le prix de la tâche.
`429`	`RATE_LIMITED`	Trop de soumissions de tâches par minute. Réessayez plus tard.
`429`	`CONCURRENCY_LIMITED`	Trop de tâches inachevées. Attendez qu’une tâche se termine.
`503`	`EXECUTION_UNAVAILABLE`	L’exécution n’est pas configurée pour ce modèle actuellement.
`429`	`UPSTREAM_RATE_LIMITED`	The model provider is rate limiting chat requests. Retry with backoff; nothing was charged.
`502`	`UPSTREAM_ERROR`	The model provider failed the chat request. Nothing was charged; retry later.
`503`	`PLATFORM_BUDGET_EXCEEDED`	This model is temporarily unavailable. Try again later.
`503`	`EXECUTION_TEMPORARILY_UNAVAILABLE`	L’exécution est temporairement indisponible. Réessayez avec la même Idempotency-Key.
`503`	`AUTH_UNAVAILABLE`	L’authentification est temporairement indisponible. Réessayez plus tard.
`503`	`API_UNAVAILABLE`	L’API est temporairement indisponible. Réessayez plus tard.

Guide complet de l’API · OpenAPI 3.1

Prix Hermes AI

Chargement du prix…

Prix catalogue officiel

Tarifs API standard du fabricant en USD, avant remises de canal. Les unités et spécifications suivent la source officielle.

Prix officiel non vérifié pour ce modèle.

Ce qui influe sur le coût

Resolution, duration and output quantity can affect the quote. Review the rate card and the Playground quote before submitting.

· Only successful tasks are charged. Failed tasks release reserved credits; tasks with an unconfirmed outcome keep their reservation until the result is verified.
· Les nouvelles tentatives idempotentes avec la même clé ne créent pas de second débit.
· Envoyez expectedPriceMicros pour rejeter la tâche avec PRICE_CHANGED si le prix a changé après son affichage.

Estimation

Select the specifications in Playground to see the task quote.

// Facturation

Fonctionnement de la facturation

Tasks use prepaid credits. Add credits on the Billing page; your balance updates after payment confirmation.

Quand	Effet
Task accepted	The quoted amount is reserved from your balance.
Task succeeded	The final amount is charged once and any unused reservation is returned.
Task failed	The reserved amount is returned to your available balance.

Tasks with an unconfirmed outcome keep their reserved credits until the result is verified. Keep the task ID and contact support if you need help.

Payment refunds are reflected in your balance and transaction history on the Billing page.

Requête minimale

Champs obligatoires uniquement, générée à partir du schéma de ce modèle. Définissez HERMES_API_KEY dans votre environnement.

# 1. Submit the task (asynchronous; returns 202 with a task id)
curl -X POST https://api.hermes-ai.net/api/v1/jobs \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "model": "flux-3-text-to-image",
  "input": {
    "prompt": "A lighthouse on a rocky coast at sunrise, soft light",
    "resolution": "1k"
  }
}'

# 2. Poll until status is succeeded, failed or reconciliation_required
curl https://api.hermes-ai.net/api/v1/jobs/TASK_ID \
  -H "Authorization: Bearer $HERMES_API_KEY"

Avec les valeurs par défaut documentées

La même requête avec chaque valeur par défaut facultative explicitée, pour voir ce qu’il faut modifier.

# 1. Submit the task (asynchronous; returns 202 with a task id)
curl -X POST https://api.hermes-ai.net/api/v1/jobs \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "model": "flux-3-text-to-image",
  "input": {
    "prompt": "A lighthouse on a rocky coast at sunrise, soft light",
    "resolution": "1k",
    "aspectRatio": "1:1",
    "grounding": true,
    "safetyTolerance": 2
  }
}'

# 2. Poll until status is succeeded, failed or reconciliation_required
curl https://api.hermes-ai.net/api/v1/jobs/TASK_ID \
  -H "Authorization: Bearer $HERMES_API_KEY"