Génération d'images

Démarrage rapide

Le point de terminaison image natif est synchrone par défaut. Définissez le booléen async sur true pour créer une tâche en arrière-plan. Cet exemple utilise qwen-image-2.0.

curl -X POST https://aihubmix.com/ai/v1/images/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
    "n": 1,
    "size": "1024x1024",
    "async": true
  }'

{
  "id": "task_01K0ABCDEF",
  "object": "image",
  "model": "qwen-image-2.0",
  "status": "in_progress",
  "output": [],
  "error": null,
  "created_at": 1784707200,
  "completed_at": null,
  "expires_at": null
}

curl https://aihubmix.com/ai/v1/images/{id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

curl "{content_url}" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.png

Comment découvrir les modèles média asynchrones et obtenir leurs schémas ?

La découverte se déroule en deux étapes. Récupérez d’abord dans le catalogue public les modèles texte-image ou texte-vidéo compatibles avec les API asynchrones. Utilisez ensuite le model_id du modèle pour obtenir le schéma de requête de ses endpoints.

Lister les modèles compatibles avec les API asynchrones

Le catalogue de modèles utilise la même source de données que Playground. Utilisez type=image_generation pour les modèles texte-image et type=video pour les modèles texte-vidéo. Le paramètre schema_checked=true limite la liste aux modèles dont le schéma de requête a été publié et vérifié.

# Modèles texte-image
curl "https://aihubmix.com/api/v1/models?type=image_generation&schema_checked=true&sort_by=order"

# Modèles texte-vidéo
curl "https://aihubmix.com/api/v1/models?type=video&schema_checked=true&sort_by=order"

Les deux requêtes utilisent le même endpoint. Le filtre type accepte actuellement une seule valeur. Interrogez donc chaque type de modèle séparément. La réponse suit la forme {success, message, data}. Les champs de data utiles aux intégrations média asynchrones sont les suivants.

Champ	Description
`data[].model_id`	ID du modèle utilisé pour la génération et les requêtes de schéma suivantes
`data[].model_name`	Nom d’affichage du modèle
`data[].types`	Types séparés par des virgules, avec éventuellement `image_generation` et `llm`
`data[].input_modalities`	Modalités d’entrée séparées par des virgules
`data[].schema_checked`	`true` lorsque le schéma de requête a été publié et vérifié

{
  "success": true,
  "message": "",
  "data": [
    {
      "model_id": "qwen-image-2.0",
      "model_name": "Qwen Image 2.0",
      "types": "image_generation",
      "input_modalities": "text,image",
      "schema_checked": true
    }
  ]
}

Obtenir le schéma de requête d’un modèle

Les champs, les valeurs d’énumération et les plages numériques pris en charge peuvent varier selon le modèle. Avant d’envoyer une requête d’image ou de vidéo, utilisez l’endpoint public ci-dessous pour récupérer les endpoints disponibles et les schémas JSON de requête du modèle sélectionné.

# Modèle texte-image
curl "https://aihubmix.com/call/schema/models/qwen-image-2.0/endpoints"

# Modèle texte-vidéo
curl "https://aihubmix.com/call/schema/models/wan2.6-t2v/endpoints"

La valeur modality de la réponse est image ou video. Chaque élément du tableau endpoints décrit un protocole d’appel disponible.

Champ	Description
`default_endpoint`	Identifiant de l’endpoint par défaut du modèle
`endpoints[].endpoint`	Identifiant de l’endpoint
`endpoints[].method`	Méthode HTTP, par exemple `POST`
`endpoints[].path`	Chemin de la requête
`endpoints[].content_types`	Types de contenu acceptés par l’endpoint
`endpoints[].lifecycle`	Mode synchrone ou asynchrone, chemin d’interrogation et valeurs de statut
`endpoints[].request.schema`	Schéma JSON complet de la requête pour ce modèle et cet endpoint, avec les champs requis et les contraintes de valeurs

Un modèle peut renvoyer des endpoints /ai/v1 ainsi que des endpoints /v1 compatibles avec OpenAI. Les endpoints compatibles avec OpenAI peuvent ne pas encore prendre en charge les modèles les plus récents. Utilisez donc de préférence les endpoints /ai/v1. Pour les API de tâches asynchrones, sélectionnez l’élément dont le path est /ai/v1/images/generations ou /ai/v1/videos, puis utilisez son request.schema. Ne dépendez pas de la position d’un élément dans le tableau endpoints. Les commandes suivantes extraient directement le schéma de requête de chaque endpoint de tâche asynchrone.

# Texte-image
curl -s "https://aihubmix.com/call/schema/models/qwen-image-2.0/endpoints" \
  | jq '.endpoints[] | select(.path == "/ai/v1/images/generations") | .request.schema'

# Texte-vidéo
curl -s "https://aihubmix.com/call/schema/models/wan2.6-t2v/endpoints" \
  | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema'

L’endpoint renvoie 404 model_not_found si le modèle n’existe pas ou ne dispose d’aucun endpoint détectable. Il renvoie 500 endpoints_unavailable lorsque les données des endpoints sont temporairement indisponibles.

Comment créer une tâche d’image ?

Image synchrone

Lorsque async est omis ou vaut false, l’API attend la fin de la génération et renvoie l’objet tâche :

curl -X POST https://aihubmix.com/ai/v1/images/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

Les tâches d’image synchrones sont également enregistrées. Si la connexion du client est interrompue ou si la réponse de création est perdue, utilisez GET /ai/v1/images pour retrouver la tâche.

Image asynchrone

Lorsque async vaut le booléen true, l’API renvoie immédiatement l’objet tâche et la génération se poursuit en arrière-plan :

curl -X POST https://aihubmix.com/ai/v1/images/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
    "n": 2,
    "size": "1024x1024",
    "async": true
  }'

Consultez la tâche avec GET /ai/v1/images/{id}. Une fois terminée, demandez directement le content_url de chaque élément output. Cette URL contient le result_id de l’image correspondante.

Dans une requête d’image, async doit être un booléen. webhook_url et webhook_events_filter ne peuvent être utilisés qu’avec async: true.

Champs standard des images

Champ	Type	Obligatoire	Description
`model`	string	Oui	Nom du modèle
`prompt`	string	Oui	Description de l’image, non vide
`n`	integer/null	Non	Nombre d’images, minimum `1`, valeur par défaut `1`
`size`	string/null	Non	`{width}x{height}`, par exemple `1024x1024`
`aspect_ratio`	string/null	Non	Rapport largeur-hauteur, mutuellement exclusif avec `size`
`seed`	integer/null	Non	Graine aléatoire
`negative_prompt`	string/null	Non	Prompt négatif
`image`	string/object	Non	Image d’entrée unique sous forme d’URL, de Data URI, de Base64 ou d’objet `{url}`
`images`	array/null	Non	Plusieurs images d’entrée
`mask`	string/object	Non	Masque de modification d’image
`output_format`	string/null	Non	`png`, `jpeg` ou `webp`, valeur par défaut `png`
`response_format`	string/null	Non	`url` ou `b64_json`, valeur par défaut `url`
`async`	boolean	Non	Exécution asynchrone si la valeur est `true`
`webhook_url`	string	Non	Adresse de rappel HTTPS, 512 caractères maximum
`webhook_events_filter`	string[]	Non	Sous-ensemble non vide de `completed`, `failed`, `cancelled`
`extra`	object/null	Non	Paramètres étendus propres au modèle

Objet de tâche média

Les API propres aux images et aux vidéos renvoient la structure suivante :

{
  "id": "task_01K0ABCDEF",
  "object": "image",
  "model": "qwen-image-2.0",
  "status": "completed",
  "output": [
    {
      "index": 0,
      "type": "file",
      "b64_json": null,
      "content_url": "https://aihubmix.com/ai/v1/images/task_01K0ABCDEF/content/result_01K0XYZ"
    }
  ],
  "error": null,
  "created_at": 1784707200,
  "completed_at": 1784707320,
  "expires_at": null
}

Champ	Type	Description
`id`	string	ID de tâche de la plateforme
`object`	string	`image` ou `video`
`model`	string	Nom du modèle
`status`	string	Statut actuel de la tâche
`output`	array	Résultats générés, tableau vide s’il n’y en a pas encore
`error`	object/null	Informations d’échec, pouvant contenir `code`, `message` et `upstream_detail`
`created_at`	integer	Date de création, en secondes Unix
`completed_at`	integer/null	Date du statut final, en secondes Unix
`expires_at`	null	Les API propres aux médias renvoient actuellement `null`

Élément output d’un média :

Champ	Type	Description
`index`	integer	Ordre du résultat, à partir de `0`
`type`	string	Vaut actuellement `file`
`content_url`	string/null	Adresse de téléchargement du résultat
`b64_json`	string/null	Résultat d’image encodé en Base64

Description des statuts

Statut	Terminé	Description
`pending`	Non	La plateforme a reçu la tâche, en attente d’exécution
`in_progress`	Non	La tâche est en cours d’exécution
`completed`	Oui	La tâche est terminée, `output` est disponible
`failed`	Oui	La tâche a échoué, consulter `error`
`cancelled`	Oui	La tâche a été annulée

Le client peut interroger la tâche toutes les 15 secondes jusqu’au statut completed, failed ou cancelled. Cet intervalle de 15 secondes est une recommandation pour le polling côté client, pas une restriction du protocole serveur.

Comment consulter les tâches média ?

Consulter le détail d’un média

# Image
curl https://aihubmix.com/ai/v1/images/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# Vidéo
curl https://aihubmix.com/ai/v1/images/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

Les API de détail média peuvent renvoyer un statut actualisé. Utilisez donc l’API de détail d’image ou de vidéo correspondante pour le polling.

Lister les médias

Si la réponse de création est perdue, retrouvez l’ID de tâche dans la liste du média correspondant :

curl "https://aihubmix.com/ai/v1/images?limit=20&order=desc" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

Paramètre	Type	Valeur par défaut	Description
`after`	string	-	Curseur de pagination, utiliser le `next_after` de la page précédente
`limit`	integer	`20`	Nombre d’éléments par page, maximum `100`
`order`	string	`desc`	Ordre croissant avec `asc`, toute autre valeur est traitée comme `desc`

{
  "object": "list",
  "data": [
    {
      "id": "task_01K0ABCDEF",
      "object": "image",
      "model": "qwen-image-2.0",
      "status": "in_progress",
      "output": [],
      "error": null,
      "created_at": 1784707200,
      "completed_at": null,
      "expires_at": null
    }
  ],
  "has_more": true,
  "next_after": "task_01K0ABCDEF"
}

La liste média renvoie un instantané au moment de la consultation et n’actualise pas activement le statut des tâches.

Comment utiliser l’API de tâches unifiées ?

L’API de tâches unifiées accepte les filtres suivants :

curl "https://aihubmix.com/ai/v1/tasks?object=image&status=in_progress&limit=20&order=desc" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

Paramètre	Type	Valeur par défaut	Description
`object`	string	-	`llm`, `image` ou `video`
`status`	string	-	`pending`, `in_progress`, `completed`, `failed` ou `cancelled`
`model`	string	-	Filtre exact par nom de modèle
`after`	string	-	Curseur de pagination
`limit`	integer	`20`	Plage de `1` à `100`
`order`	string	`desc`	`asc` ou `desc`

Détail d’une tâche unifiée :

curl https://aihubmix.com/ai/v1/tasks/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

Élément output unifié d’une tâche média :

{
  "index": 0,
  "result_id": "result_01K0XYZ",
  "type": "file",
  "content_type": "image/png",
  "content_url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content/result_01K0XYZ"
}

Pour un résultat unique, demandez directement /ai/v1/tasks/{id}/content. Pour plusieurs résultats, demandez /ai/v1/tasks/{id}/content/{result_id}. Sans ID de résultat, l’API renvoie 400 result_id_required.

Les API de liste, de détail et de contenu des tâches unifiées sont isolées selon le Bearer Token qui a créé la tâche. Une autre clé API du même compte ne peut pas lire cette tâche.

Télécharger les résultats média

Télécharger des images

Une fois l’image terminée, demandez chaque output[].content_url de l’objet de tâche média :

curl "{content_url}" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.png

Le chemin de téléchargement média d’une image est /ai/v1/images/{id}/content/{result_id}. L’objet de tâche média n’expose pas result_id séparément. Le client peut utiliser directement content_url. Lorsque b64_json n’est pas vide, décodez directement ce champ en Base64.

Utiliser un Webhook

Les images asynchrones et les vidéos prennent en charge les Webhooks au niveau de la tâche :

curl -X POST https://aihubmix.com/ai/v1/images/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "A tranquil garden at sunrise",
    "n": 1,
    "async": true,
    "size": "1024x1024",
    "webhook_url": "https://example.com/webhooks/aihubmix",
    "webhook_events_filter": ["completed", "failed"]
  }'

webhook_url est limité à 512 caractères et ne peut pas pointer vers la machine locale, un réseau privé ou une autre adresse restreinte. Lorsque webhook_events_filter est omis, la plateforme envoie completed, failed et cancelled. Lorsqu’il est fourni, le tableau ne peut pas être vide ni contenir de doublons, et doit être utilisé avec webhook_url. Si webhook_url est absent de la requête, les images asynchrones et les vidéos tentent d’utiliser l’adresse de rappel par défaut du compte. Une adresse par défaut non valide est ignorée et ne bloque pas la création de la tâche.

Requête de rappel

{
  "event_id": "evt_01K0ABCDEF",
  "event_type": "completed",
  "created_at": "2026-08-12T12:00:00Z",
  "data": {
    "task_id": "task_01K0ABCDEF",
    "status": "completed",
    "model": "qwen-image-2.0",
    "results": [
      {
        "url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content/result_01K0XYZ"
      }
    ]
  }
}

Champ	Description
`event_id`	ID de l’événement de rappel, utilisé pour la déduplication
`event_type`	`completed`, `failed` ou `cancelled`
`created_at`	Date de l’événement au format RFC 3339
`data.task_id`	ID de tâche de la plateforme
`data.status`	Statut final actuel
`data.model`	Nom du modèle
`data.results[].url`	Adresse de téléchargement éventuellement renvoyée à la fin
`data.error`	Informations d’erreur éventuellement renvoyées en cas d’échec

results n’apparaît que si le résultat a été archivé. Le téléchargement nécessite toujours un Bearer Token.

Nouvelles tentatives et déduplication

La plateforme utilise une livraison au moins une fois. Un même événement peut être envoyé plusieurs fois :

HTTP 2xx indique une réception réussie.
HTTP 5xx, une erreur réseau ou un délai dépassé déclenchent une nouvelle tentative.
HTTP 3xx et 4xx ne déclenchent pas de nouvelle tentative.
Six livraisons au maximum, avec des intervalles successifs de 1, 4, 16, 64 et 256 secondes.

Le destinataire doit enregistrer event_id et renvoyer immédiatement 2xx s’il reçoit à nouveau le même événement.

Le Webhook au niveau de la tâche n’a pas de clé de signature indépendante. Si une vérification de signature est nécessaire, configurez un abonnement Webhook au niveau du compte et conservez la consultation du détail de la tâche comme méthode de confirmation du résultat.

Réponses et codes d’erreur

Cette section s’applique à /ai/v1/images/* et aux tâches d’image. Pour les erreurs vidéo, consultez l’API vidéo.

Échec de la requête en cours : un statut HTTP hors 2xx indique que la requête de création, de consultation ou de téléchargement a échoué. Voir Échecs des requêtes HTTP.
Échec d’exécution de la tâche : la consultation renvoie HTTP 200, mais la tâche porte status=failed, avec la cause enregistrée dans son champ error. Voir Échecs d’exécution des tâches.
Échec de lecture du résultat d’une ligne de liste : la liste renvoie HTTP 200, mais une tâche comporte output_error. Voir Échecs de lecture des résultats individuels d’une liste.

Les colonnes message ci-dessous contiennent les messages de réponse en anglais. Les descriptions en expliquent le sens et le traitement. Les erreurs de validation des paramètres présentent un message générique ; la réponse réelle peut préciser les champs et contraintes concernés. Les clients doivent identifier le type d’erreur à partir de code, sans dépendre d’une correspondance avec le message complet.

{
  "error": {
    "message": "The task was not found.",
    "type": "invalid_request_error",
    "code": "task_not_found",
    "tid": "req_01K0ABCDEF"
  }
}

Signaler une erreur HTTP 5xx

Lorsqu’une requête renvoie HTTP 5xx, signalez le problème en joignant error.tid.

Échecs des requêtes HTTP

Les statuts HTTP ci-dessous s’appliquent à l’échec direct de la requête en cours. Pour les échecs d’exécution après la création d’une tâche, consultez le tableau Échecs d’exécution des tâches ci-dessous.

Paramètres de requête et médias d’entrée

HTTP	`code`	`message`	Description
400	`invalid_request`	`Invalid request. Check the request body and parameters.`	Le corps de la requête, les paramètres de requête ou leurs types sont incorrects. Vérifiez le format, les types et les valeurs des paramètres en suivant le message d’erreur.
404	`model_not_found`	`The requested model was not found. Check the model name.`	Le modèle demandé n’existe pas. Vérifiez son nom.
400	`schema_violation`	`One or more model parameters are invalid. Check the model schema and request values.`	Les paramètres ne respectent pas les exigences d’entrée du modèle choisi. Consultez son schéma et corrigez les champs indiqués dans le message d’erreur.
400	`unsupported_input_combination`	`This model does not support this operation or media input combination. Change the inputs or choose another model.`	Le modèle ne prend pas en charge cette combinaison d’opération et de médias d’entrée. Modifiez la combinaison ou choisissez un modèle compatible.
400	`capability_not_supported`	`One or more requested parameters are not supported by this model. Change the parameters or choose another model.`	Les paramètres demandés dépassent les capacités du modèle. Ajustez-les selon le message d’erreur ou choisissez un autre modèle.
400	`unsupported_media_format`	`The {media_kind} format is not supported for this model.`	Le modèle ne prend pas en charge ce format de média. Utilisez un format indiqué dans le message d’erreur ou dans `error.details.allowed_mime_types`. En l’absence de liste, consultez les exigences d’entrée du modèle.
400	`invalid_media_data`	`The media data is invalid. Provide valid media data.`	Les données du média sont confirmées comme non valides, par exemple un encodage base64 corrompu ou une URI data mal formée. Vérifiez l’intégrité et l’encodage des données, puis fournissez un média valide.
400	`media_url_unreachable`	`The media URL could not be accessed. Make sure it is publicly accessible and returns valid media data.`	L’URL du média est inaccessible ou illisible. Vérifiez qu’elle est valide, accessible publiquement et qu’elle renvoie un contenu média valide.
400	`invalid_media`	`The media input could not be processed. Check that its data or URL is valid and uses a supported format.`	Le média d’entrée n’a pas pu être traité et la cause précise ne peut pas être confirmée actuellement. Vérifiez la validité des données ou de l’URL et la prise en charge du format par le modèle.
413	`image_too_large`	`The image is too large. Reduce the image size to {max_bytes} bytes or less and try again.`	Le contenu média de la tâche d’image dépasse la limite de traitement actuelle. Réduisez sa taille selon `error.details.max_bytes` ou la limite indiquée dans le message d’erreur, puis réessayez.
413	`request_too_large`	`The request body exceeds the 32 MiB limit. Reduce the request size and try again.`	Le corps HTTP complet dépasse 32 MiB. Réduisez le corps réellement envoyé, y compris le texte, les paramètres et l’encodage des médias intégrés.

Limites de taille

Taille du média : les tâches d’image dépassant la limite renvoient image_too_large. La limite exacte figure dans le message d’erreur ou dans error.details.max_bytes.
Taille totale de la requête : request_too_large signifie que le corps HTTP dépasse 32 MiB, y compris le texte, les paramètres et l’encodage des médias intégrés. Lorsqu’une URL seule est fournie, elle compte dans la taille du corps ; le fichier qu’elle désigne doit aussi respecter les limites de média du modèle.
Taille réelle : error.details.actual_bytes est fourni uniquement lorsque la taille complète est confirmée. Lors de la lecture d’un média par URL, ce champ peut être absent si la lecture s’arrête à la limite.

Formats pris en charge Les formats dépendent du modèle choisi. Consultez d’abord error.details.allowed_mime_types ou la liste de formats du message d’erreur. En l’absence de liste, consultez le Schema du modèle. Variables dans les messages

{media_kind} : le type réel de média. Lorsque ce type est confirmé, les messages de invalid_media_data et media_url_unreachable utilisent également image ou video.
{max_bytes} : la limite en octets. Si la limite de l’image est inconnue, la réponse est The image is too large. Reduce the image size and try again.
{allowed_formats} : la liste des formats autorisés. Les messages d’erreur de format peuvent ajouter Use one of: {allowed_formats}.

Requêtes de génération et résultats renvoyés

HTTP	`code`	`message`	Description
502	`image_not_generated`	`The model provider completed the request but did not return an image. Adjust the request or choose another model, then try again. If the problem persists, contact support with the request ID.`	Le fournisseur de modèles a terminé la requête sans renvoyer d’image exploitable. Modifiez la requête ou choisissez un autre modèle, puis réessayez. Si l’échec persiste, contactez l’assistance avec l’ID de requête. Ne relancez pas automatiquement la génération sans condition au seul motif du statut HTTP 502.
422	`output_blocked`	`The model provider blocked the generated output. Change the prompt or input content and try again.`	Le fournisseur de modèles a bloqué le contenu généré et n’a renvoyé aucune image exploitable. Modifiez le prompt ou le contenu d’entrée, puis réessayez. Aucun frais de génération n’est facturé pour cette tentative.
400	`upstream_rejected`	`The model provider rejected the request. Check the request parameters and content.`	Le fournisseur de modèles a rejeté la requête. Ce code seul ne permet pas de conclure à une violation de la politique de contenu. Vérifiez et modifiez les paramètres et le contenu d’entrée, puis réessayez.
502	`upstream_bad_response`	`The model provider response could not be processed. Contact support with the request ID.`	Le fournisseur de modèles a renvoyé une réponse que la plateforme n’a pas pu traiter. Cela ne confirme pas l’absence de résultat généré. Contactez l’assistance avec l’ID de requête ; ne concluez pas vous-même à une erreur de paramètre ou à un résultat vide.
400	`doubao_real_person_required`	`This request uses a real-person image. Complete real-person verification and use an active asset reference. See https://docs.aihubmix.com/cn/api/doubao-real-person-assets.`	Doubao a renvoyé un code de rejet spécifique à la confidentialité d’une image de personne réelle. Effectuez la vérification d’identité, puis utilisez une ressource `asset://` activée. Consultez la documentation des ressources de personnes réelles.
504	`sync_timeout`	`Generation did not complete within the waiting period. Contact support with the request ID.`	La génération n’a pas abouti pendant le délai d’attente. Ce dépassement ne prouve pas que la requête n’a pas été exécutée. Contactez l’assistance avec l’ID de requête ; ne consultez pas un ID de tâche qui ne vous a pas été renvoyé.
502	`task_status_unavailable`	`The model provider task state could not be confirmed. Do not submit it again. Contact support with the task ID or request ID.`	La tâche a été soumise au fournisseur de modèles, mais son état ultérieur ne peut pas être confirmé. Ne la soumettez pas à nouveau. Contactez l’assistance avec l’ID de requête et, si disponible, l’ID de tâche.

Compte et autorisations

HTTP	`code`	`message`	Description
401	`authentication_failed`	`Authentication failed: invalid or missing API key.`	La clé API est absente ou non valide. Vérifiez l’en-tête `Authorization` et la clé API.
402	`insufficient_quota`	`Your account has insufficient quota. Add credits and try again.`	Le quota du compte est insuffisant. Ajoutez du crédit, puis réessayez.
403	`permission_denied`	`You do not have permission to access this resource. Check the account, API key permissions, and IP restrictions.`	Le compte ou la clé API n’a pas accès à la ressource. Vérifiez les autorisations du compte et de la clé API ainsi que les restrictions IP.
403	`async_not_enabled`	`Asynchronous tasks are not enabled. Please go to https://console.aihubmix.com/async-tasks to activate.`	Les tâches asynchrones ne sont pas activées pour ce compte. Activez-les via le lien de console fourni dans la réponse, puis réessayez.

Disponibilité du service et limites de débit

HTTP	`code`	`message`	Description
429	`rate_limited`	`Too many requests. Reduce the request rate and try again later.`	Les requêtes sont trop fréquentes. Réduisez leur fréquence, puis réessayez.
429	`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	Le fournisseur de modèles limite le débit. Réessayez plus tard et évitez les soumissions répétées immédiatement.
500	`internal_error`	`An internal error occurred. Contact support with the request ID.`	La plateforme a rencontré une erreur interne. Contactez l’assistance avec l’ID de requête. Il est inutile de modifier à répétition des entrées valides.
502	`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	Le fournisseur de modèles est temporairement indisponible, éventuellement en raison d’un échec de connexion, d’une erreur de son service ou d’un échec de lecture de la réponse. Ce code seul ne permet pas de confirmer si un résultat a été généré. Si l’échec persiste, contactez l’assistance avec l’ID de requête.
502	`provider_unavailable`	`The model provider is unavailable. Contact support with the request or task ID.`	Le fournisseur de modèles est indisponible. Le tableau présente le message par défaut ; la réponse réelle peut donner des indications plus précises. Identifiez le type d’erreur à partir de `code`. Contactez l’assistance avec l’ID de requête.
503	`model_unavailable`	`The requested model is temporarily unavailable. Try again later or choose another model. If the problem persists, contact support with the request ID.`	Le modèle demandé est temporairement indisponible. Réessayez plus tard ou choisissez un autre modèle. Si l’échec persiste, contactez l’assistance avec l’ID de requête.
503	`service_unavailable`	`The service is temporarily unavailable. Try again later. If the problem persists, contact support with the request ID.`	Le service est temporairement indisponible. Réessayez l’opération en cours plus tard. Si un téléchargement échoue, relancez le téléchargement sans nouvelle génération.

provider_unavailable indique une défaillance du fournisseur de modèles explicitement identifiée. Un simple statut 429 ou 4xx ne permet pas de confirmer un problème de quota, de modération du contenu ou de paramètres.

Consultation des tâches et téléchargement des résultats

HTTP	`code`	`message`	Description
404	`task_not_found`	`The task was not found.`	La tâche n’existe pas ou n’appartient pas au compte actuel. Vérifiez l’ID de tâche et assurez-vous que la clé API appartient au compte ayant créé la tâche.
404	`result_not_found`	`The result was not found.`	Le résultat n’existe pas ou n’est pas accessible. Vérifiez l’ID de tâche, l’ID de résultat et la clé API. Un ID de résultat connu comme non valide ne devient pas une erreur 409 du seul fait que la tâche est encore en cours.
400	`invalid_cursor`	`The cursor is invalid or expired. Start a new list request.`	Le curseur de pagination est non valide ou a expiré. Supprimez `after`, recommencez à la première page, puis utilisez le nouveau curseur renvoyé par cette liste.
400	`result_id_required`	`This task has multiple results. Specify result_id.`	La tâche a plusieurs résultats, mais aucun `result_id` n’a été précisé. Sélectionnez un résultat dans la sortie de la tâche et indiquez son `result_id`.
409	`result_not_ready`	`The result is not available yet. Check the task status before downloading.`	La tâche est encore en attente ou en cours, et le résultat n’est pas prêt. Continuez à consulter son statut et téléchargez le résultat lorsqu’il est prêt. Une nouvelle génération est inutile.
410	`artifact_expired`	`The result has expired and is no longer available. Submit a new generation request.`	La durée de conservation du résultat est écoulée. Les résultats expirés ne peuvent plus être téléchargés. Soumettez une nouvelle requête de génération si nécessaire.
429	`too_many_downloads`	`Download limit exceeded for this result.`	La limite de téléchargements est atteinte. Vérifiez les résultats déjà enregistrés. Attendre ne garantit pas le rétablissement du nombre de téléchargements disponibles.

Échecs d’exécution des tâches

Après la création réussie d’une tâche, un échec de génération est signalé par status=failed et le champ error de la tâche. Une consultation réussie renvoie toujours HTTP 200.

{
  "id": "task_01K0ABCDEF",
  "object": "image",
  "status": "failed",
  "output": [],
  "error": {
    "code": "image_not_generated",
    "message": "The model provider completed the request but did not return an image. Adjust the request or choose another model, then submit a new task."
  }
}

Task `code`	`message`	Description
`image_not_generated`	`The model provider completed the request but did not return an image. Adjust the request or choose another model, then submit a new task.`	Le fournisseur de modèles a terminé la requête sans renvoyer d’image exploitable. Modifiez la requête ou choisissez un autre modèle, puis soumettez une nouvelle tâche. Ne relancez pas automatiquement la génération sans condition.
`output_blocked`	`The model provider blocked the generated output. Change the prompt or input content and try again.`	Le fournisseur de modèles a bloqué le contenu généré et n’a renvoyé aucune image exploitable. Modifiez le prompt ou le contenu d’entrée, puis soumettez une nouvelle tâche. Aucun frais de génération n’est facturé pour cette tentative.
`output_policy_violation`	`Generated content was rejected by the content policy.`	Le contenu généré n’a pas passé la modération. Modifiez le prompt ou le contenu d’entrée, puis soumettez une nouvelle tâche. Les règles existantes de facturation de la modération s’appliquent ; les frais antérieurs sont indiqués dans l’historique de facturation.
`upstream_rejected`	`The model provider rejected the request. Check the request parameters and content.`	Le fournisseur de modèles a rejeté la requête. Ce code seul ne permet pas de conclure à une violation de la politique de contenu. Vérifiez et modifiez les paramètres et le contenu d’entrée, puis soumettez une nouvelle tâche.
`upstream_bad_response`	`The model provider response could not be processed. Contact support with the task ID.`	La plateforme n’a pas pu traiter la réponse du fournisseur de modèles. Cela ne confirme pas l’absence de résultat généré. Contactez l’assistance avec l’ID de tâche.
`task_status_unavailable`	`The model provider task state could not be confirmed. Do not submit it again. Contact support with the task ID.`	La tâche a été soumise au fournisseur de modèles, mais son état ultérieur ne peut pas être confirmé. Ne la soumettez pas à nouveau. Contactez l’assistance avec l’ID de tâche.
`result_delivery_failed`	`The generated result could not be delivered. Do not resubmit automatically. Contact support with the task ID.`	Un résultat a été généré, mais la plateforme n’a pas pu terminer son enregistrement ou sa livraison. Ne relancez pas automatiquement la génération. Contactez l’assistance avec l’ID de tâche pour examiner d’abord le résultat existant.
`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	Le fournisseur de modèles limite le débit. Réessayez plus tard et évitez les soumissions répétées immédiatement.
`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	Un échec de connexion au fournisseur de modèles, une erreur de son service ou un échec de lecture de sa réponse est survenu pendant l’exécution. Ce code seul ne permet pas de confirmer si un résultat a été généré. Si l’échec persiste, contactez l’assistance avec l’ID de tâche.
`provider_unavailable`	`The model provider is unavailable. Contact support with the request or task ID.`	Le fournisseur de modèles est indisponible. Le tableau présente le message par défaut ; la réponse réelle peut donner des indications plus précises. Identifiez le type d’erreur à partir de `code`. Contactez l’assistance avec l’ID de tâche.
`doubao_real_person_required`	`This request uses a real-person image. Complete real-person verification and use an active asset reference. See https://docs.aihubmix.com/cn/api/doubao-real-person-assets.`	Doubao a renvoyé un code de rejet spécifique à la confidentialité d’une image de personne réelle. Effectuez la vérification d’identité, puis utilisez une ressource `asset://` activée. Consultez la documentation des ressources de personnes réelles.
`sync_timeout`	`Generation timed out. Contact support with the task ID.`	Le délai de génération de la tâche a été dépassé. Contactez l’assistance avec l’ID de tâche.
`internal_error`	`An internal error occurred. Contact support with the task ID.`	La plateforme a rencontré une erreur interne. Contactez l’assistance avec l’ID de tâche. Il est inutile de modifier à répétition des entrées valides.

Les erreurs de média d’entrée peuvent aussi apparaître dans les tâches en échec. Leurs codes gardent le sens indiqué dans le tableau des médias d’entrée ci-dessus ; les consultations réussies renvoient toujours HTTP 200. Pour les erreurs de taille de média, le message se termine par submit a new task., afin d’indiquer de réduire le média avant de soumettre une nouvelle tâche. output_blocked indique un blocage explicite sans image exploitable renvoyée ; aucun frais de génération n’est facturé pour cette tentative. Les règles existantes de facturation de la modération s’appliquent à output_policy_violation. Consultez l’historique de facturation pour les frais antérieurs.

Échecs de lecture des résultats individuels d’une liste

Certaines lignes des listes de tâches d’image et de vidéo peuvent comporter output_error :

{
  "output_error": {
    "code": "internal_error",
    "type": "server_error",
    "message": "The task output could not be read. Contact support with the request ID.",
    "tid": "req_01K0ABCDEF"
  }
}

Ce champ indique que le résultat de cette ligne n’a pas pu être lu pour la requête en cours. La liste renvoie toujours HTTP 200, avec output=[] pour cette ligne. Ses champs id, status et error ainsi que la pagination restent inchangés, et les autres tâches lisibles ne sont pas affectées. Même avec status=completed, vérifiez output_error avant de déterminer si le résultat peut être lu. Contactez l’assistance avec output_error.tid. Si ce champ ne contient pas de tid, fournissez l’ID de requête des en-têtes de la réponse en cours. Cette erreur ne modifie ni le statut de la tâche ni les frais, et ne déclenche pas de Webhook. Les listes d’images et de vidéos conservent la valeur expires_at déjà obtenue. Dans la liste unifiée /ai/v1/tasks, les lignes dont le résultat n’a pas pu être lu peuvent renvoyer expires_at=null ; la durée de conservation initiale continue de s’appliquer. Ce traitement s’applique uniquement lorsqu’un résultat individuel est illisible et qu’aucune solution de repli n’est disponible. L’échec de consultation de tout un lot dans l’API de tâches unifiées renvoie toujours une erreur HTTP ; le même type d’échec lors de la lecture des détails renvoie toujours HTTP 500. Documentation associée : API image · API vidéo · Tâches asynchrones

Exemple complet

Ces exemples créent une tâche asynchrone, l’interrogent et enregistrent chaque image retournée.

import base64
import os
import time

import requests

base_url = "https://aihubmix.com"
headers = {
    "Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}",
    "Content-Type": "application/json",
}

response = requests.post(
    f"{base_url}/ai/v1/images/generations",
    headers=headers,
    json={
        "model": "qwen-image-2.0",
        "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
        "n": 1,
        "size": "1024x1024",
        "async": True,
    },
    timeout=60,
)
response.raise_for_status()
task = response.json()

while task["status"] not in {"completed", "failed", "cancelled"}:
    time.sleep(15)
    response = requests.get(
        f"{base_url}/ai/v1/images/{task['id']}",
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()

if task["status"] != "completed":
    raise RuntimeError(task.get("error") or task["status"])

for output in task["output"]:
    filename = f"result-{output['index']}.png"
    if output.get("b64_json"):
        content = base64.b64decode(output["b64_json"])
    else:
        result = requests.get(output["content_url"], headers=headers, timeout=120)
        result.raise_for_status()
        content = result.content
    with open(filename, "wb") as file:
        file.write(content)

import { writeFile } from "node:fs/promises";

const baseUrl = "https://aihubmix.com";
const headers = {
  Authorization: `Bearer ${process.env.AIHUBMIX_API_KEY}`,
  "Content-Type": "application/json",
};

const created = await fetch(`${baseUrl}/ai/v1/images/generations`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "qwen-image-2.0",
    prompt: "A flower shop with delicate windows, warm sunlight streaming in",
    n: 1,
    size: "1024x1024",
    async: true,
  }),
});
if (!created.ok) throw new Error(await created.text());
let task = await created.json();

const finished = new Set(["completed", "failed", "cancelled"]);
while (!finished.has(task.status)) {
  await new Promise((resolve) => setTimeout(resolve, 15_000));
  const polled = await fetch(`${baseUrl}/ai/v1/images/${task.id}`, { headers });
  if (!polled.ok) throw new Error(await polled.text());
  task = await polled.json();
}

if (task.status !== "completed") {
  throw new Error(JSON.stringify(task.error ?? task.status));
}

for (const output of task.output) {
  let content;
  if (output.b64_json) {
    content = Buffer.from(output.b64_json, "base64");
  } else {
    const result = await fetch(output.content_url, { headers });
    if (!result.ok) throw new Error(await result.text());
    content = Buffer.from(await result.arrayBuffer());
  }
  await writeFile(`result-${output.index}.png`, content);
}

Démarrage

Fonctionnalités passerelle

Capacités des modèles

Référence du protocole

Gestion de la plateforme

Génération d'images

Démarrage rapide

Comment découvrir les modèles média asynchrones et obtenir leurs schémas ?

Lister les modèles compatibles avec les API asynchrones

Obtenir le schéma de requête d’un modèle

Comment créer une tâche d’image ?

Image synchrone

Image asynchrone

Champs standard des images

Objet de tâche média

Description des statuts

Comment consulter les tâches média ?

Consulter le détail d’un média

Lister les médias

Comment utiliser l’API de tâches unifiées ?

Télécharger les résultats média

Télécharger des images

Utiliser un Webhook

Requête de rappel

Nouvelles tentatives et déduplication

Réponses et codes d’erreur

Signaler une erreur HTTP 5xx

Échecs des requêtes HTTP

Paramètres de requête et médias d’entrée

Requêtes de génération et résultats renvoyés

Compte et autorisations

Disponibilité du service et limites de débit

Consultation des tâches et téléchargement des résultats

Échecs d’exécution des tâches

Échecs de lecture des résultats individuels d’une liste

Exemple complet

​Démarrage rapide

​Comment découvrir les modèles média asynchrones et obtenir leurs schémas ?

​Lister les modèles compatibles avec les API asynchrones

​Obtenir le schéma de requête d’un modèle

​Comment créer une tâche d’image ?

​Image synchrone

​Image asynchrone

​Champs standard des images

​Objet de tâche média

​Description des statuts

​Comment consulter les tâches média ?

​Consulter le détail d’un média

​Lister les médias

​Comment utiliser l’API de tâches unifiées ?

​Télécharger les résultats média

​Télécharger des images

​Utiliser un Webhook

​Requête de rappel

​Nouvelles tentatives et déduplication

​Réponses et codes d’erreur

Signaler une erreur HTTP 5xx

​Échecs des requêtes HTTP

​Paramètres de requête et médias d’entrée

​Requêtes de génération et résultats renvoyés

​Compte et autorisations

​Disponibilité du service et limites de débit

​Consultation des tâches et téléchargement des résultats

​Échecs d’exécution des tâches

​Échecs de lecture des résultats individuels d’une liste

​Exemple complet

Démarrage rapide

Comment découvrir les modèles média asynchrones et obtenir leurs schémas ?

Lister les modèles compatibles avec les API asynchrones

Obtenir le schéma de requête d’un modèle

Comment créer une tâche d’image ?

Image synchrone

Image asynchrone

Champs standard des images

Objet de tâche média

Description des statuts

Comment consulter les tâches média ?

Consulter le détail d’un média

Lister les médias

Comment utiliser l’API de tâches unifiées ?

Télécharger les résultats média

Télécharger des images

Utiliser un Webhook

Requête de rappel

Nouvelles tentatives et déduplication

Réponses et codes d’erreur

Échecs des requêtes HTTP

Paramètres de requête et médias d’entrée

Requêtes de génération et résultats renvoyés

Compte et autorisations

Disponibilité du service et limites de débit

Consultation des tâches et téléchargement des résultats

Échecs d’exécution des tâches

Échecs de lecture des résultats individuels d’une liste

Exemple complet