API Image en image

L'API Image en image est une fonctionnalité qui vous permet d'intégrer les capacités d'édition d'images par IA de Meshy dans votre propre application. Transformez et modifiez des images existantes à l'aide d'images de référence et d'invites textuelles grâce à nos puissants modèles d'IA.

POST/openapi/v1/image-to-image

Créer une tâche Image en image

Ce point de terminaison vous permet de créer une nouvelle tâche Image en image. Reportez-vous à L'objet tâche Image en image pour voir quelles propriétés sont incluses dans l'objet tâche Image 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 plus fortes que 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'édition d'image haute fidélité (12 crédits par image)
- gpt-image-2-5-flare : OpenAI GPT Image 2.5 (Flare), un modèle d'édition d'image haute fidélité (12 crédits par image)
- gpt-image-2-5-sunburst : OpenAI GPT Image 2.5 (Sunburst), un modèle d'édition d'image haute fidélité (12 crédits par image)
Name
prompt
Type
string
Requis
Description
Une description textuelle de la transformation ou de la modification que vous souhaitez appliquer aux images de référence.

Un seul des paramètres input_task_id ou reference_image_urls est requis. Si les deux sont fournis, input_task_id a la priorité.

Name
input_task_id
Type
string
Requis
Description
L'ID d'une tâche de génération d'image terminée dont les images de sortie doivent être utilisées comme images de référence. Cette tâche doit être l'une des suivantes : Texte en image ou Image en image, y compris leurs variantes multi-vue. De plus, elle doit avoir été exécutée via l'API et avoir un statut SUCCEEDED.
Toutes les images de sortie de la tâche source sont utilisées. Une tâche à image unique fournit 1 image de référence ; une tâche multi-vue en fournit une par vue générée, de sorte qu'un seul ID de tâche peut remplir plusieurs des 5 emplacements de référence.
La tâche source doit toujours être dans la période de conservation des ressources — une fois expirée, son ID renvoie 404.

Name
reference_image_urls
Type
array
Requis
Description
Un tableau de 1 à 5 images de référence à utiliser pour la tâche d'édition d'image. Nous prenons actuellement en charge les formats .jpg, .jpeg, et .png.
Il existe deux façons de fournir chaque image :
- URL accessible publiquement : Une URL accessible depuis l'internet public.
- Data URI : Une data URI encodée en base64 de l'image. Exemple de data URI : data:image/jpeg;base64,<vos données d'image encodées en base64>.

Name
generate_multi_view
Type
boolean
défaut false
Description
Lorsqu'il est défini sur true, génère une image multi-vue montrant le sujet sous plusieurs angles.
Lorsque generate_multi_view vaut true, le paramètre aspect_ratio ne peut pas être défini.
Name
aspect_ratio
Type
string
défaut 1:1
Description
Spécifiez le rapport hauteur/largeur de l'image de sortie. Les valeurs autorisées dépendent de l'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 grand écran
- 9:16 : Portrait grand écran
- 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
Lorsqu'il est défini sur true, l'image de sortie 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 nouvelle tâche Image en image 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, ou ni reference_image_urls ni input_task_id n'ont été fournis.
- Tâche d'entrée invalide : input_task_id doit référencer une tâche Texte en image ou Image en image (y compris multi-vue) avec le statut SUCCEEDED qui dispose encore d'images en sortie. Une tâche de tout autre type, une tâche qui n'a pas réussi, ou une tâche dont toutes les images ont expiré est rejetée.
- Format d'image invalide : Une ou plusieurs images de référence ne sont pas dans des formats pris en charge.
- URL inaccessible : Une ou plusieurs reference_image_urls n'ont pas pu être téléchargées.
- Paramètre invalide : aspect_ratio n'est pas l'une des valeurs autorisées pour l'ai_model sélectionné.
- 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
404 - Not Found
Description
input_task_id ne fait pas référence à une tâche appartenant à votre compte. Une tâche qui n'existe pas et une tâche appartenant à un autre compte renvoient la même réponse.
Name
429 - Too Many Requests
Description
Vous avez dépassé votre limite de débit.

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

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

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

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

Paramètres

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

Retours

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

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

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

Supprimer une tâche Image en image

Ce point de terminaison supprime définitivement une tâche Image 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 Image en image à supprimer.

Statut de la tâche

Une tâche toujours en statut PENDING est supprimée et les crédits consommés lors de sa 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 déjà démarrée par le worker ne sont pas remboursables, donc la supprimer en cours d'exécution vous ferait 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 final (SUCCEEDED, FAILED ou CANCELED) est supprimée sans remboursement.

Retours

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

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 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/image-to-image

Lister les tâches Image en image

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

Paramètres

Name
page_num
Type
integer
Description
Numéro de page pour la pagination. Commence à 1 et vaut 1 par défaut.
Name
page_size
Type
integer
Description
Limite de taille de page. La valeur par défaut est 10 éléments. Le maximum autorisé est 100 éléments.
Name
sort_by
Type
string
Description
Champ selon lequel trier. 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.

Retourne

Retourne une liste paginée d'objets de tâche Image en image.

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

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

Diffuser en continu une tâche Image en image

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

Paramètres

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

Retours

Renvoie un flux d'objets de tâche Image 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/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.
// 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": "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=***"
  ]
}

The Image to Image Task Object

L'objet Image to Image Task est une unité de travail que Meshy suit pour générer une image à partir d'images de référence et d'un prompt textuel en entrée. L'objet possède les propriétés suivantes :

Properties

Name
id
Type
string
Description
Identifiant unique de la tâche. Bien que nous utilisions un UUID k-triable 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 Image to Image, cette valeur sera toujours image-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 utilisé pour guider la transformation de 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 commencé, 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, conformément à la norme RFC 3339. Par exemple, le vendredi 1er septembre 2023 à 12:00:00 GMT est représenté par 1693569600000. Cela s'applique à tous les horodatages de 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'a de sens 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 de l'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. Retourne 0 pour les tâches FAILED (les crédits sont remboursés en cas d'échec).

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
}