API Texte en image

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

Texte en image crée des images. Pour créer un modèle 3D à partir du contenu d'une image, utilisez Image en 3D. Pour créer un objet que vous pouvez tenir en main ou imprimer à partir d'une photo, utilisez les API Creative Lab. Elles génèrent une image de prototype puis construisent un modèle 3D à partir de celle-ci, par exemple un porte-clés, un aimant de frigo, une figurine, une lampe ou un capuchon de touche.

POST/openapi/v1/text-to-image

Create a Text to Image task

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 Processing times.

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 Pricing.
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-pro : le modèle Pro, avec une qualité supérieure. Nécessite un forfait Pro ou supérieur. Avec un forfait 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)
Name
prompt
Type
string
Requis
Description
Texte décrivant 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 montrant le sujet sous plusieurs angles. Lorsque c'est true, vous ne pouvez pas envoyer aspect_ratio. Envoyer les deux renvoie 400.
Name
pose_mode
Type
string
Description
La pose d'un personnage, a-pose ou t-pose. Omettez ce paramètre pour n'avoir aucune pose.
Le fonctionnement d'une pose dépend de ai_model :
- nano-banana-2 et nano-banana-2-lite : 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 affiche nano-banana-pro en retour. Cela nécessite un forfait 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 et gpt-image-2-5-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 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, afin que vous puissiez 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 quel problème a été 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 envoyez-la à nouveau. Consultez Errors.
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 :
- Forfait gratuit : la création d'une tâche nécessite un forfait payant. Mettez à niveau votre forfait dans vos paramètres d'abonnement, puis réessayez.
- Crédits insuffisants : le compte ne dispose pas de suffisamment de crédits pour cette tâche (Insufficient funds), ou le compte a atteint une limite de crédits.
- Forfait requis : la requête utilise nano-banana-pro, ou pose_mode avec nano-banana, sur un forfait 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 forfait, puis réessayez.
Name
429 - Too Many Requests
Description
Vous avez dépassé votre limite de débit. Patientez, puis réessayez. Consultez Rate limits.

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 texte. Il contient le statut, la progression, et les URL 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,
  "preceding_tasks": 0,
  "image_urls": [
    "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
  ],
  "task_error": {

    "message": ""

  },

  "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-pro
- gpt-image-2
- gpt-image-2-5-flare
- gpt-image-2-5-sunburst
Name
prompt
Type
string
Description
Le prompt texte avec lequel vous avez créé la tâche.
Name
status
Type
string
Description
Le statut de la tâche, l'un des suivants : 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 à laquelle la tâche a été créée, en millisecondes Unix.
Name
started_at
Type
timestamp
Description
Heure à laquelle la tâche a démarré, en millisecondes Unix. Elle vaut 0 tant que la tâche n'a pas démarré.
Name
finished_at
Type
timestamp
Description
Heure à laquelle la tâche s'est terminée, en millisecondes Unix. Elle vaut 0 tant que la tâche n'est pas terminée.
Name
expires_at
Type
timestamp
Description
Heure à laquelle les résultats de la tâche expirent, en millisecondes Unix.
Name
preceding_tasks
Type
integer
Description
Le nombre de tâches qui précèdent celle-ci dans la file d'attente. Cette valeur n'a de sens que tant que la tâche est PENDING.
Name
image_urls
Type
array
Description
Les URL 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 toutes les vues, il en renvoie moins, et la tâche réussit quand 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. 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.