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.

Image en image crée des images. Pour créer un modèle 3D à partir de ce qui se trouve dans une image, utilisez Image en 3D. Pour créer un objet que vous pouvez tenir ou imprimer à partir d'une photo, utilisez les API Creative Lab. Elles créent 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 keycap.

POST/openapi/v1/image-to-image

Create an Image to Image task

Crée une tâche Image en image. La tâche s'exécute en arrière-plan. Pour la durée habituelle d'une tâche, consultez Temps 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 varient 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-pro : le modèle Pro, de meilleure qualité. Il 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)
Name
prompt
Type
string
Requis
Description
Texte qui décrit la modification ou la transformation à appliquer aux images de référence.

Name
input_task_id
Type
string
Requis
Description
Obligatoire sauf si vous envoyez reference_image_urls. L'ID d'une tâche Texte en image ou Image en image dont les images doivent servir de références, y compris les tâches multi-vue. La tâche doit être une tâche que vous avez créée avec l'API et dont le statut est SUCCEEDED.
Meshy utilise toutes les images produites 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 toujours 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
Obligatoire 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 d'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 × 32 pixels.

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 true, vous ne pouvez pas envoyer aspect_ratio. Envoyer les deux renvoie 400.
Name
aspect_ratio
Type
string
défaut 1:1
Description
Le rapport d'aspect de l'image de sortie. 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 GPT Image sont gpt-image-2, gpt-image-2-5-flare et gpt-image-2-5-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 trouvé. 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 avec le statut SUCCEEDED, multi-vue incluse, qui dispose encore d'images en sortie. 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 grande : Une ou plusieurs images reference_image_urls dépassent 20 Mo.
- Image trop petite : Une ou plusieurs images reference_image_urls sont plus petites que 32 × 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 crédits suffisants 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 qui n'existe pas 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, le progress, 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,
  "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 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-pro
- gpt-image-2
- gpt-image-2-5-flare
- gpt-image-2-5-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 part de la tâche déjà accomplie, en pourcentage. Elle est à 0 jusqu'à ce que la tâche démarre 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. Elle est à 0 jusqu'à ce que la tâche démarre.
Name
finished_at
Type
timestamp
Description
Heure de fin de la tâche, en millisecondes Unix. Elle est à 0 jusqu'à ce que la tâche se termine.
Name
expires_at
Type
timestamp
Description
Heure d'expiration des résultats de la tâche, en millisecondes Unix.
Name
preceding_tasks
Type
integer
Description
Le nombre de tâches devant 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, 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. 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.