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 Image en image

Modifiez et transformez des images dans votre propre application. Envoyez des images de référence et un prompt textuel, et les modèles d'IA de Meshy génèrent une nouvelle image à partir de ceux-ci.


POST/openapi/v1/image-to-image

Créer une tâche Image en image

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

Request

POST
/openapi/v1/image-to-image
# Transform a reference image with a text prompt
curl https://api.meshy.ai/openapi/v1/image-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "reference_image_urls": [
      "<your publicly accessible image url or base64-encoded data URI>"
    ]
  }'


 ## Using data URI example
curl https://api.meshy.ai/openapi/v1/image-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "reference_image_urls": [
      "data:image/png;base64,${YOUR_BASE64_ENCODED_IMAGE_DATA}"
    ]
  }'


 ## Chaining from a previous task, instead of passing image URLs
curl https://api.meshy.ai/openapi/v1/image-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "input_task_id": "<your Text to Image or Image to Image task id>"
  }'

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 diffèrent selon le modèle. 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. Il nécessite un plan Pro ou supérieur. Avec 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 décrivant la modification ou la transformation à appliquer aux images de référence.

  • Name
    input_task_id
    Type
    string
    Requis
    Description

    Requis sauf si vous envoyez reference_image_urls. L'ID d'une tâche Texte en image ou Image en image dont les images servent de références, y compris les tâches multi-vue. La tâche doit être une tâche que vous avez créée via l'API et dont le statut est SUCCEEDED.

    Meshy utilise chaque image produite par la tâche. Une tâche à image unique fournit une image de référence, et une tâche multi-vue en fournit une par vue. Ainsi, un seul ID de tâche peut remplir plusieurs des cinq emplacements de référence.

    La tâche doit encore se trouver dans la période de conservation des ressources. Une fois cette période expirée, son ID renvoie 404.

  • Name
    reference_image_urls
    Type
    array
    Requis
    Description

    Requis sauf si vous envoyez input_task_id. Une à cinq images de référence à modifier, chacune étant une URL publique ou un Data URI, par exemple data:image/jpeg;base64,<vos données image encodées en base64>. Un tableau vide, ou plus de cinq images, renvoie 400. Si vous envoyez les deux, Meshy utilise input_task_id.

    Chaque image doit être un fichier .jpg, .jpeg, .png ou .webp d'au plus 20 Mo, et d'au moins 32 pixels de côté.

  • 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 true, vous ne pouvez pas envoyer aspect_ratio. Envoyer les deux renvoie 400.

  • Name
    aspect_ratio
    Type
    string
    défaut 1:1
    Description

    Le format d'image de l'image de sortie. Les valeurs que vous pouvez envoyer dépendent de ai_model.

    Valeurs disponibles :

    • 1:1 : carré
    • 16:9 : paysage large
    • 9:16 : portrait large
    • 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 GPT Image sont gpt-image-2, gpt-image-2-5-flare, gpt-image-2-5-sunburst, gpt-image-2-6-flare et gpt-image-2-6-sunburst. Avec un modèle nano-banana, 3:2 et 2:3 renvoient 400.

  • Name
    remove_background
    Type
    boolean
    défaut false
    Description

    Indique s'il faut supprimer l'arrière-plan. Lorsque true, Meshy renvoie l'image de sortie sous forme de 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 Image 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, tel que ai_model ou prompt, est manquant, ou ni reference_image_urls ni input_task_id n'a été envoyé.
    • Tâche d'entrée invalide : input_task_id ne pointe pas vers une tâche utilisable. Il doit s'agir d'une tâche Texte en image ou Image en image SUCCEEDED, multi-vue incluse, qui possède encore une sortie image. Meshy rejette une tâche d'un autre type, une tâche qui n'a pas réussi, et une tâche dont toutes les images ont expiré.
    • Format d'image invalide : une ou plusieurs images de référence ne sont pas dans un format pris en charge.
    • URL inaccessible : Meshy ne peut pas télécharger une ou plusieurs images reference_image_urls.
    • Image trop volumineuse : une ou plusieurs images reference_image_urls dépassent 20 Mo.
    • Image trop petite : une ou plusieurs images reference_image_urls ont un côté inférieur à 32 pixels.
    • Paramètre invalide : aspect_ratio ne correspond à aucune des valeurs prises en charge par le ai_model sélectionné.
    • Conflit : la requête envoie aspect_ratio avec generate_multi_view: true.

    Corrigez la requête, puis envoyez-la à nouveau. 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 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, ou le compte a atteint une limite de crédits.
    • Plan requis : la requête utilise nano-banana-pro sur un plan inférieur à Pro.

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

  • Name
    404 - Not Found
    Description

    input_task_id ne correspond à aucune tâche de votre compte. Une tâche inexistante et une tâche appartenant à un autre compte renvoient la même réponse. Vérifiez l'ID.

  • 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/image-to-image/:id

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

Renvoie une tâche Image en image par son ID.

Request

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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 tâche provenant de la réponse de création.

Retours

L'objet tâche Image en image.


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

Supprimer une tâche Image en image

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

Request

DELETE
/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/image-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/image-to-image

Lister les tâches Image en image

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

Request

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "image-to-image",
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "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 : les plus anciennes en premier
    • -created_at : les plus récentes en premier

Retours

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


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

Diffuser une tâche d'image en image

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

Request

GET
/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.ai/openapi/v1/image-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": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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'identifiant de la tâche issu de la réponse de création.

Retour

Un flux d'objets de tâche Image 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 valeurs.


L'objet de tâche Image en image

Un objet de tâche Image en image décrit une image générée à partir d'images de référence et d'un prompt textuel. Il contient le statut, la progression et les images lorsque la tâche réussit.

Propriétés

Example Image to Image Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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 image-to-image.

  • Name
    ai_model
    Type
    string
    Description

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

    Valeurs disponibles :

    • 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 qui a guidé la modification.

  • 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 proportion de la tâche accomplie, en pourcentage. Elle est à 0 tant que la tâche n'a pas commencé et à 100 lorsqu'elle réussit.

  • Name
    created_at
    Type
    timestamp
    Description

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

  • Name
    started_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

    Horodatage 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

    Horodatage 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. Cette valeur n'a de sens que lorsque la tâche est PENDING. Ce champ est omis lorsque la valeur est 0.

  • Name
    image_urls
    Type
    array
    Description

    Les URL de téléchargement des images générées. Avec generate_multi_view: true, elle contient une URL par vue, généralement trois. Si Meshy ne parvient pas à séparer chaque vue, elle en renvoie moins, et la tâche réussit quand même. Sinon, elle 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 est à 0 pour une tâche FAILED, car Meshy rembourse les crédits lorsqu'une tâche échoue.