API Texte en image

L'API Texte en image est une fonctionnalité qui vous permet d'intégrer les capacités de génération d'images par IA de Meshy dans votre propre application. Générez des images de haute qualité à partir d'invites textuelles grâce à nos puissants modèles d'IA.

POST/openapi/v1/text-to-image

Créer une tâche Texte en image

Ce point de terminaison vous permet de créer une nouvelle tâche Texte en image. Consultez L'objet tâche Texte en image pour voir quelles propriétés sont incluses dans l'objet tâche Texte en image.

Paramètres

Name
ai_model
Type
string
Requis
Description
ID du modèle à utiliser pour la génération d'image.
Valeurs disponibles :
- nano-banana : modèle standard (3 crédits par image)
- nano-banana-2 : modèle équilibré avec des capacités supérieures au modèle standard (6 crédits par image)
- nano-banana-pro : modèle Pro avec une qualité améliorée (9 crédits par image)
- gpt-image-2 : OpenAI GPT Image 2, un modèle d'image haute fidélité (9 crédits par image)
- gpt-image-2-5-flare : OpenAI GPT Image 2.5 (Flare), un modèle d'image haute fidélité (9 crédits par image)
- gpt-image-2-5-sunburst : OpenAI GPT Image 2.5 (Sunburst), un modèle d'image haute fidélité (9 crédits par image)
Name
prompt
Type
string
Requis
Description
Une description textuelle de l'image que vous souhaitez générer. Soyez descriptif pour obtenir les meilleurs résultats.
Name
generate_multi_view
Type
boolean
défaut false
Description
Lorsque défini sur true, génère une image multi-vue montrant le sujet sous plusieurs angles.
Lorsque generate_multi_view est true, le paramètre aspect_ratio ne peut pas être défini.
Name
pose_mode
Type
string
Description
Spécifiez le pose_mode pour la génération de personnage. Lorsqu'il est omis, l'image est générée sans aucun préréglage de pose.
Valeurs disponibles : a-pose, t-pose
Name
aspect_ratio
Type
string
défaut 1:1
Description
Spécifiez le format d'image de l'image générée. Les valeurs autorisées dépendent du ai_model sélectionné :
- nano-banana, nano-banana-2, nano-banana-pro : 1:1, 16:9, 9:16, 4:3, 3:4
- gpt-image-2, gpt-image-2-5-flare, gpt-image-2-5-sunburst : 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3
Valeurs disponibles :
- 1:1 : format carré
- 16:9 : paysage écran large
- 9:16 : portrait écran large
- 4:3 : paysage standard
- 3:4 : portrait standard
- 3:2 : paysage (uniquement pris en charge par les modèles GPT Image)
- 2:3 : portrait (uniquement pris en charge par les modèles GPT Image)
Name
remove_background
Type
boolean
défaut false
Description
Lorsque défini sur true, l'image générée est renvoyée sous forme de PNG RGBA transparent avec l'arrière-plan supprimé, ce qui vous permet de composer le sujet sur n'importe quel arrière-plan.

Retours

La propriété result de la réponse contient l'id de la tâche de la tâche Texte en image nouvellement créée.

Modes d'échec

Name
400 - Bad Request
Description
La requête était inacceptable. Causes courantes :
- Paramètre manquant : un paramètre requis (par exemple, ai_model, prompt) est manquant.
- Paramètre invalide : ai_model ou aspect_ratio n'est pas l'une des valeurs autorisées.
- Conflit : generate_multi_view et aspect_ratio ne peuvent pas être utilisés simultanément.
Name
401 - Unauthorized
Description
L'authentification a échoué. Veuillez vérifier votre clé API.
Name
402 - Payment Required
Description
Crédits insuffisants pour effectuer cette tâche.
Name
429 - Too Many Requests
Description
Vous avez dépassé votre limite de débit.

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"
}

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

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

Ce point de terminaison vous permet de récupérer une tâche Texte en image à partir d'un id de tâche valide. Consultez L'objet tâche Texte en image pour voir les propriétés incluses dans l'objet tâche Texte en image.

Paramètres

Name
id
Type
path
Description
Identifiant unique de la tâche Texte en image à récupérer.

Retour

La réponse contient l'objet tâche Texte en image. Consultez la section L'objet tâche Texte en image pour plus de détails.

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=***"
  ]
}

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

Supprimer une tâche Texte en image

Ce point de terminaison supprime définitivement une tâche Texte en image, y compris toutes les images et données associées. Cette action est irréversible.

Paramètres de chemin

Name
id
Type
path
Description
L'ID de la tâche Texte en image à supprimer.

Statut de la tâche

Une tâche encore PENDING est supprimée et les crédits consommés au moment de la création sont remboursés.

Une tâche déjà IN_PROGRESS ne peut pas être supprimée : la requête est rejetée avec 409 Conflict et la tâche continue de s'exécuter. Les crédits d'une tâche que le worker a déjà commencé à traiter ne sont pas remboursables ; la supprimer en cours d'exécution vous ferait donc perdre à la fois les crédits et le résultat. Attendez qu'elle atteigne l'état SUCCEEDED, FAILED ou CANCELED, puis supprimez-la.

Une tâche dans un état terminal (SUCCEEDED, FAILED ou CANCELED) est supprimée sans remboursement.

Retourne

Retourne 200 OK en cas de succès, ou 409 Conflict lorsque la tâche est IN_PROGRESS.

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 is left 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."
}

GET/openapi/v1/text-to-image

Lister les tâches Texte en image

Ce point de terminaison vous permet de récupérer une liste de tâches Texte en image.

Paramètres

Name
page_num
Type
integer
Description
Numéro de page pour la pagination. Commence et vaut par défaut 1.
Name
page_size
Type
integer
Description
Limite de taille de page. La valeur par défaut est 10 éléments. Le maximum autorisé est de 100 éléments.
Name
sort_by
Type
string
Description
Champ utilisé pour le tri. Valeurs disponibles :
- +created_at : Trier par date de création par ordre croissant.
- -created_at : Trier par date de création par ordre décroissant.

Retours

Retourne une liste paginée d'Objets de tâche Texte en image.

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=***"
    ]
  }
]

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

Diffuser une tâche Texte en image

Ce point de terminaison diffuse les mises à jour en temps réel d'une tâche Texte en image à l'aide des Server-Sent Events (SSE).

Paramètres

Name
id
Type
path
Description
Identifiant unique de la tâche Texte en image à diffuser.

Retours

Renvoie un flux d'objets de tâche Texte en image sous forme de Server-Sent Events.

Pour les tâches PENDING ou IN_PROGRESS, le flux de réponse n'inclura que les champs progress et status nécessaires.

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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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=***"
  ]
}

L'objet de tâche Text to Image

L'objet de tâche Text to Image est une unité de travail que Meshy suit pour générer une image à partir d'une entrée de prompt textuel. L'objet possède les propriétés suivantes :

Propriétés

Name
id
Type
string
Description
Identifiant unique de la tâche. Bien que nous utilisions un UUID k-sortable pour les identifiants de tâche comme détail d'implémentation, vous ne devez pas faire d'hypothèses sur le format de l'id.
Name
type
Type
string
Description
Le type de tâche de génération d'image. Pour les tâches Text to Image, ce sera toujours text-to-image.
Name
ai_model
Type
string
Description
Le modèle d'IA utilisé pour cette tâche. Les valeurs possibles sont nano-banana, nano-banana-2, nano-banana-pro, gpt-image-2, gpt-image-2-5-flare, ou gpt-image-2-5-sunburst.
Name
prompt
Type
string
Description
Le prompt textuel qui a été utilisé pour générer l'image.
Name
status
Type
string
Description
Statut de la tâche. Les valeurs possibles sont l'une des suivantes : PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progression de la tâche. Si la tâche n'a pas encore démarré, cette propriété sera 0. Une fois la tâche réussie, elle deviendra 100.
Name
created_at
Type
timestamp
Description
Horodatage de la création de la tâche, en millisecondes.
Un horodatage représente le nombre de millisecondes écoulées depuis le 1er janvier 1970 UTC, suivant la norme RFC 3339. Par exemple, le vendredi 1er septembre 2023 à 12h00:00 GMT est représenté par 1693569600000. Cela s'applique à tous les horodatages dans Meshy API.
Name
started_at
Type
timestamp
Description
Horodatage du démarrage de la tâche, en millisecondes. Si la tâche n'a pas encore démarré, cette propriété sera 0.
Name
finished_at
Type
timestamp
Description
Horodatage de la fin de la tâche, en millisecondes. Si la tâche n'est pas encore terminée, cette propriété sera 0.
Name
expires_at
Type
timestamp
Description
Horodatage de l'expiration du résultat de la tâche, en millisecondes.
Name
preceding_tasks
Type
integer
Description
Le nombre de tâches précédentes.
La valeur de ce champ n'est significative que si le statut de la tâche est PENDING.
Name
image_urls
Type
array
Description
Un tableau d'URL téléchargeables vers les images générées. Lorsque generate_multi_view est activé, ce tableau contient trois URL d'images représentant différents angles de vue. Sinon, il contient une seule URL d'image.
Name
task_error
Type
object
Description
Détails d'erreur pour les tâches échouées. Consultez Erreurs pour la référence complète de l'objet task_error.
Name
consumed_credits
Type
integer
Description
Le nombre de crédits consommés par cette tâche. Présent lorsque le statut de la tâche est PENDING, IN_PROGRESS, ou SUCCEEDED. Renvoie 0 pour les tâches FAILED (les crédits sont remboursés en cas d'échec).

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
}