lowpoly sera retiré le 30 oct. 2026. meshy-7 sera retiré en tant que modèle de génération 3D le 31 déc. 2026 ; il reste disponible en tant que modèle de texture. Changez de modèle avant ces dates pour éviter les erreurs de requête. Voir toutes les dépréciations

API Texte en image

Générez des images à partir d'un prompt textuel grâce aux modèles d'IA de Meshy.


POST/openapi/v1/text-to-image

Créer une tâche Texte en image

Crée une tâche Texte en image. La tâche s'exécute en arrière-plan. Pour connaître la durée habituelle d'une tâche, consultez Temps de traitement.

Request

POST
/openapi/v1/text-to-image
# Generate an image from a text prompt
curl https://api.meshy.ai/openapi/v1/text-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "A majestic dragon soaring through clouds at sunset",
    "aspect_ratio": "16:9"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Paramètres

  • Name
    ai_model
    Type
    string
    Requis
    Description

    Le modèle d'IA qui génère l'image. Les prix varient selon le modèle. Pour les prix, consultez Tarification.

    Valeurs disponibles :

    • nano-banana : le modèle standard
    • nano-banana-2 : plus performant que nano-banana
    • nano-banana-2-lite : une version allégée de nano-banana-2
    • nano-banana-2-1 : Nano Banana 2.1
    • nano-banana-pro : le modèle Pro, avec une qualité supérieure. Nécessite un plan Pro ou supérieur. Sur un plan inférieur, il renvoie 402.
    • gpt-image-2 : OpenAI GPT Image 2
    • gpt-image-2-5-flare : OpenAI GPT Image 2.5 (Flare)
    • gpt-image-2-5-sunburst : OpenAI GPT Image 2.5 (Sunburst)
    • gpt-image-2-6-flare : OpenAI GPT Image 2.6 (Flare)
    • gpt-image-2-6-sunburst : OpenAI GPT Image 2.6 (Sunburst)
  • Name
    prompt
    Type
    string
    Requis
    Description

    Texte qui décrit l'image à générer. Une description détaillée donne de meilleurs résultats.

  • Name
    generate_multi_view
    Type
    boolean
    défaut false
    Description

    Indique s'il faut générer une image Multi-vue qui montre le sujet sous plusieurs angles. Lorsque c'est true, vous ne pouvez pas envoyer aspect_ratio. L'envoi des deux renvoie 400.

  • Name
    pose_mode
    Type
    string
    Description

    La pose pour un personnage, a-pose ou t-pose. Omettez ce paramètre pour aucune pose.

    Le fonctionnement d'une pose dépend de ai_model :

    • nano-banana-2, nano-banana-2-lite et nano-banana-2-1 : Meshy conserve le modèle que vous avez choisi. L'image est toujours au format 3:4, et Meshy ignore aspect_ratio.
    • nano-banana et nano-banana-pro : Meshy génère l'image avec nano-banana-pro, de sorte que le champ ai_model de la tâche indique alors nano-banana-pro. Cela nécessite un plan Pro ou supérieur. L'image est toujours au format 3:4, et Meshy ignore aspect_ratio.
    • Les modèles GPT Image (gpt-image-2, gpt-image-2-5-flare, gpt-image-2-5-sunburst, gpt-image-2-6-flare et gpt-image-2-6-sunburst) : Meshy conserve le modèle que vous avez choisi ainsi que votre aspect_ratio.
  • Name
    aspect_ratio
    Type
    string
    défaut 1:1
    Description

    La forme de l'image. Les valeurs que vous pouvez envoyer dépendent de ai_model.

    Valeurs disponibles :

    • 1:1 : carré
    • 16:9 : paysage grand écran
    • 9:16 : portrait grand écran
    • 4:3 : paysage standard
    • 3:4 : portrait standard
    • 3:2 : paysage, modèles GPT Image uniquement
    • 2:3 : portrait, modèles GPT Image uniquement

    Les modèles nano-banana (nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-2-1 et nano-banana-pro) renvoient 400 pour 3:2 et 2:3.

  • Name
    remove_background
    Type
    boolean
    défaut false
    Description

    Indique s'il faut supprimer l'arrière-plan de l'image. true renvoie un PNG RGBA transparent, ce qui vous permet de placer le sujet sur n'importe quel arrière-plan.

Retours

Le champ result de la réponse contient l'ID de la nouvelle tâche Texte en image.

Modes d'échec

  • Name
    400 - Bad Request
    Description

    La requête ne peut pas s'exécuter. Le message d'erreur indique le problème détecté. Par exemple :

    • Paramètre manquant : un paramètre requis, comme ai_model ou prompt, est manquant.
    • Paramètre invalide : ai_model ou aspect_ratio n'est pas l'une des valeurs autorisées.
    • Conflit : aspect_ratio a été envoyé avec generate_multi_view: true.

    Corrigez la requête, puis renvoyez-la. Consultez Erreurs.

  • Name
    401 - Unauthorized
    Description

    La clé API est manquante ou invalide. Vérifiez l'en-tête Authorization.

  • Name
    402 - Payment Required
    Description

    Le compte ne peut pas exécuter cette tâche. Par exemple :

    • Plan gratuit : la création d'une tâche nécessite un plan payant. Mettez à niveau votre plan dans les paramètres d'abonnement, puis réessayez.
    • Crédits insuffisants : le compte n'a pas assez de crédits pour cette tâche (Insufficient funds), ou le compte a atteint une limite de crédits.
    • Plan requis : la requête utilise nano-banana-pro, ou pose_mode avec nano-banana, sur un plan inférieur à Pro (Only Pro and above users can use nano-banana-pro, ou Only Pro and above users can use A/T pose feature (requires nano-banana-pro)).

    Vérifiez votre solde de crédits et votre plan, puis réessayez.

  • Name
    429 - Too Many Requests
    Description

    Vous avez dépassé votre limite de débit. Attendez, puis réessayez. Consultez Limites de débit.


GET/openapi/v1/text-to-image/:id

Récupérer une tâche Texte en image

Renvoie une tâche Texte en image à partir de son ID.

Request

GET
/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578
curl https://api.meshy.ai/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1692771650657,
  "started_at": 1692771667037,
  "finished_at": 1692771669037,
  "expires_at": 1692771679037,
  "image_urls": [
    "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
  ]
}

Paramètres

  • Name
    id
    Type
    path
    Description

    L'ID de la tâche provenant de la réponse de création.

Retours

L'objet tâche Texte en image.


DELETE/openapi/v1/text-to-image/:id

Supprimer une tâche Texte en image

Supprime définitivement une tâche Texte en image, y compris ses images et ses données. Vous ne pouvez pas annuler une suppression.

Request

DELETE
/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

Paramètres de chemin

  • Name
    id
    Type
    path
    Description

    L'ID de la tâche à supprimer.

Statut de la tâche

Supprimer une tâche PENDING rembourse les crédits utilisés lors de sa création.

Une tâche IN_PROGRESS ne peut pas être supprimée. La requête renvoie 409 Conflict, et la tâche continue de s'exécuter. Meshy ne rembourse pas une tâche qui a démarré, donc la supprimer vous coûterait à la fois les crédits et le résultat. Attendez qu'elle atteigne le statut SUCCEEDED, FAILED ou CANCELED, puis supprimez-la.

Supprimer une tâche dans un statut final (SUCCEEDED, FAILED ou CANCELED) ne rembourse pas ses crédits.

Retours

200 OK lorsque la tâche est supprimée, ou 409 Conflict lorsque la tâche est IN_PROGRESS.


GET/openapi/v1/text-to-image

Lister les tâches Texte en image

Renvoie une liste de vos tâches Texte en image et Image en image. Le champ type de chaque tâche indique laquelle des deux il s'agit.

Request

GET
/openapi/v1/text-to-image
curl https://api.meshy.ai/openapi/v1/text-to-image?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-image",
    "ai_model": "nano-banana",
    "prompt": "A majestic dragon soaring through clouds at sunset",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1692771650657,
    "started_at": 1692771667037,
    "finished_at": 1692771669037,
    "expires_at": 1692771679037,
    "image_urls": [
      "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
    ]
  }
]

Paramètres

  • Name
    page_num
    Type
    integer
    Description

    Le numéro de page à renvoyer. Commence à 1 et vaut 1 par défaut.

  • Name
    page_size
    Type
    integer
    Description

    Le nombre de tâches par page, jusqu'à 100. La valeur par défaut est 10.

  • Name
    sort_by
    Type
    string
    Description

    L'ordre de tri.

    Valeurs disponibles :

    • +created_at : du plus ancien au plus récent
    • -created_at : du plus récent au plus ancien

Retours

Une liste paginée d'objets de tâche, au même format que l'objet de tâche Texte en image.


GET/openapi/v1/text-to-image/:id/stream

Diffuser une tâche de Texte en image

Diffuse les mises à jour d'une tâche de Texte en image sous forme d'événements envoyés par le serveur (SSE).

Request

GET
/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.ai/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// These examples are shortened. Each event holds the full task object.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1692771650657,
  "started_at": 1692771667037,
  "finished_at": 1692771669037,
  "expires_at": 1692771679037,
  "image_urls": [
    "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
  ]
}

Paramètres

  • Name
    id
    Type
    path
    Description

    L'ID de la tâche provenant de la réponse de création.

Retours

Un flux d'objets de tâche Texte en image sous forme d'événements envoyés par le serveur.

Chaque événement contient l'objet de tâche complet, dans le même format que celui renvoyé par le point de terminaison Get. Tant que la tâche est PENDING ou IN_PROGRESS, ses champs de résultat n'ont pas encore de valeur.


L'objet tâche Texte en image

Un objet tâche Texte en image décrit une génération d'image à partir d'un prompt textuel. Il contient le statut, la progression et les URLs de l'image lorsque la tâche réussit.

Propriétés

Example Text to Image Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1692771650657,
  "started_at": 1692771667037,
  "finished_at": 1692771669037,
  "expires_at": 1692771679037,
  "image_urls": [
    "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
  ],
  "task_error": null,

  "consumed_credits": 3
}
  • Name
    id
    Type
    string
    Description

    L'ID de la tâche. Traitez-le comme une chaîne opaque et ne vous fiez pas à son format.

  • Name
    type
    Type
    string
    Description

    Le type de tâche, toujours text-to-image.

  • Name
    ai_model
    Type
    string
    Description

    Le modèle d'IA utilisé par la tâche.

    Valeurs possibles :

    • nano-banana
    • nano-banana-2
    • nano-banana-2-lite
    • nano-banana-2-1
    • nano-banana-pro
    • gpt-image-2
    • gpt-image-2-5-flare
    • gpt-image-2-5-sunburst
    • gpt-image-2-6-flare
    • gpt-image-2-6-sunburst
  • Name
    prompt
    Type
    string
    Description

    Le prompt textuel avec lequel vous avez créé la tâche.

  • Name
    status
    Type
    string
    Description

    Le statut de la tâche, l'une des valeurs PENDING, IN_PROGRESS, SUCCEEDED, FAILED ou CANCELED.

  • Name
    progress
    Type
    integer
    Description

    La part de la tâche déjà accomplie, en pourcentage. Elle vaut 0 tant que la tâche n'a pas démarré et 100 lorsqu'elle réussit.

  • Name
    created_at
    Type
    timestamp
    Description

    Heure de création de la tâche, en millisecondes Unix.

  • Name
    started_at
    Type
    timestamp
    Description

    Heure de démarrage de la tâche, en millisecondes Unix. Absent tant que la tâche n'a pas démarré.

  • Name
    finished_at
    Type
    timestamp
    Description

    Heure de fin de la tâche, en millisecondes Unix. Absent tant que la tâche n'est pas terminée.

  • Name
    expires_at
    Type
    timestamp
    Description

    Heure d'expiration des résultats de la tâche, en millisecondes Unix. Absent tant que la tâche n'est pas terminée.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Le nombre de tâches qui précèdent celle-ci dans la file d'attente. La valeur n'a de sens que lorsque la tâche est PENDING. Le champ est omis lorsque la valeur est 0.

  • Name
    image_urls
    Type
    array
    Description

    Les URLs de téléchargement des images générées. Avec generate_multi_view: true, le tableau contient une URL par vue, généralement trois. Si Meshy ne parvient pas à séparer chaque vue, il en retourne moins, et la tâche réussit tout de même. Sinon, il contient une seule URL.

  • Name
    task_error
    Type
    object
    Description

    Les détails de l'erreur lorsque la tâche échoue. La valeur est null sauf si le statut est FAILED. Voir Erreurs.

  • Name
    consumed_credits
    Type
    integer
    Description

    Le nombre de crédits utilisés par la tâche. Présent lorsque le statut est PENDING, IN_PROGRESS ou SUCCEEDED. Il vaut 0 pour une tâche FAILED, car Meshy rembourse les crédits lorsqu'une tâche échoue.