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 IA de Meshy dans votre propre application. Transformez et modifiez des images existantes en utilisant des images de référence et des invites textuelles avec 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. Référez-vous à L'objet de la tâche Image en image pour voir quelles propriétés sont incluses avec l'objet de la 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'images.

    Valeurs disponibles :

    • nano-banana : Modèle standard (3 crédits par image)
    • nano-banana-2 : Modèle équilibré avec une capacité plus forte 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)
  • Name
    prompt
    Type
    string
    Requis
    Description

    Une description textuelle de la transformation ou de l'édition que vous souhaitez appliquer aux images de référence.

  • 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 supportons actuellement les formats .jpg, .jpeg, et .png.

    Il y a deux façons de fournir chaque image :

    • URL accessible publiquement : Une URL accessible depuis l'internet public.
    • Data URI : Un Data URI encodé en base64 de l'image. Exemple de Data URI : data:image/jpeg;base64,<your base64-encoded image data>.
  • 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 est 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 d'aspect de l'image de sortie. 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 : 1:1, 16:9, 9:16, 3:2, 2:3

    Valeurs disponibles :

    • 1:1 : Format carré
    • 16:9 : Paysage grand écran
    • 9:16 : Portrait grand écran
    • 4:3 : Paysage standard (non supporté par gpt-image-2)
    • 3:4 : Portrait standard (non supporté par gpt-image-2)
    • 3:2 : Paysage (uniquement supporté par gpt-image-2)
    • 2:3 : Portrait (uniquement supporté par gpt-image-2)
  • 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 le fond supprimé, vous permettant de composer le sujet sur n'importe quel fond.

Retours

La propriété result de la réponse contient l'id de la tâche Image 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, reference_image_urls) est manquant.
    • Format d'image invalide : Un ou plusieurs formats d'images de référence ne sont pas supportés.
    • 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 le 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
    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}"
    ]
  }'

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 donnée un id de tâche valide. Consultez L'objet de la tâche Image en image pour voir quelles propriétés sont incluses avec l'objet de la tâche Image en image.

Paramètres

  • Name
    id
    Type
    path
    Description

    Identifiant unique pour la tâche Image en image à récupérer.

Retours

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

Requête

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

Réponse

{
  "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.

Retours

Retourne 200 OK en cas de succès.

Requête

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

Réponse

// Returns 200 Ok on success.
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 et par défaut à 1.

  • Name
    page_size
    Type
    integer
    Description

    Limite de taille de page. Par défaut à 10 éléments. Le maximum autorisé est de 50 éléments.

  • Name
    sort_by
    Type
    string
    Description

    Champ pour trier. Valeurs disponibles :

    • +created_at: Trier par ordre croissant de la date de création.
    • -created_at: Trier par ordre décroissant de la date de création.

Retours

Retourne une liste paginée des Objets de tâche Image en image.

Requête

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

Réponse

[
  {
    "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 une tâche Image en image

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

Paramètres

  • Name
    id
    Type
    path
    Description

    Identifiant unique pour la tâche Image en image à diffuser.

Retours

Retourne un flux d'Objets de la tâche Image en image sous forme de Server-Sent Events.

Pour les tâches PENDING ou IN_PROGRESS, le flux de réponse inclura uniquement 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=***"
  ]
}

L'objet Tâche Image en image

L'objet Tâche Image en image est une unité de travail que Meshy suit pour générer une image à partir d'images de référence et d'une entrée de texte prompt. L'objet a les propriétés suivantes :

Propriétés

  • Name
    id
    Type
    string
    Description

    Identifiant unique pour la tâche. Bien que nous utilisions un UUID triable par k 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 en image, ce 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, ou gpt-image-2.

  • Name
    prompt
    Type
    string
    Description

    Le texte prompt qui a été utilisé pour guider la transformation de l'image.

  • Name
    status
    Type
    string
    Description

    Statut de la tâche. Les valeurs possibles sont PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Progression de la tâche. Si la tâche n'est pas encore commencée, 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 dans Meshy API.

  • Name
    started_at
    Type
    timestamp
    Description

    Horodatage du début de la tâche, en millisecondes. Si la tâche n'est pas encore commencée, 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 est significative uniquement si le statut de la tâche est PENDING.

  • Name
    image_urls
    Type
    array
    Description

    Un tableau d'URLs téléchargeables vers les images générées. Lorsque generate_multi_view est activé, ce tableau contient trois URLs d'image 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. Voir 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).

Exemple d'objet Tâche Image en image

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