Afbeelding naar afbeelding-API

De Afbeelding naar afbeelding-API is een functie waarmee je de AI-beeldbewerkingsmogelijkheden van Meshy kunt integreren in je eigen applicatie. Transformeer en bewerk bestaande afbeeldingen met behulp van referentieafbeeldingen en tekstprompts, met onze krachtige AI-modellen.

POST/openapi/v1/image-to-image

Een Image to Image-taak aanmaken

Met deze endpoint kunt u een nieuwe Image to Image-taak aanmaken. Raadpleeg Het Image to Image-taakobject om te zien welke eigenschappen zijn opgenomen in het Image to Image-taakobject.

Parameters

  • Name
    ai_model
    Type
    string
    Verplicht
    Description

    ID van het model dat gebruikt wordt voor het genereren van afbeeldingen.

    Beschikbare waarden:

    • nano-banana: Standaardmodel (3 credits per afbeelding)
    • nano-banana-2: Gebalanceerd model met sterkere mogelijkheden dan het standaardmodel (6 credits per afbeelding)
    • nano-banana-pro: Pro-model met verbeterde kwaliteit (9 credits per afbeelding)
    • gpt-image-2: OpenAI GPT Image 2, een zeer nauwkeurig afbeeldingsbewerkingsmodel (12 credits per afbeelding)
    • gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), een zeer nauwkeurig afbeeldingsbewerkingsmodel (12 credits per afbeelding)
    • gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), een zeer nauwkeurig afbeeldingsbewerkingsmodel (12 credits per afbeelding)
  • Name
    prompt
    Type
    string
    Verplicht
    Description

    Een tekstbeschrijving van de transformatie of bewerking die u wilt toepassen op de referentieafbeeldingen.

Slechts één van input_task_id of reference_image_urls is verplicht. Als beide worden opgegeven, heeft input_task_id prioriteit.

  • Name
    input_task_id
    Type
    string
    Verplicht
    Description

    De ID van een voltooide afbeeldingsgeneratietaak waarvan de uitvoerafbeeldingen als referentieafbeeldingen moeten worden gebruikt. Deze taak moet een van de volgende taken zijn: Tekst naar afbeelding of Afbeelding naar afbeelding, inclusief hun varianten met meerdere aanzichten. Bovendien moet de taak via de API zijn uitgevoerd en de status SUCCEEDED hebben.

    Alle uitvoerafbeeldingen van de bron taak worden gebruikt. Een taak met één afbeelding levert 1 referentieafbeelding op; een taak met meerdere aanzichten levert er één per gegenereerd aanzicht op, zodat één taak-ID meerdere van de 5 referentieslots kan vullen.

    De bron taak moet zich nog binnen de asset-retentieperiode bevinden — zodra deze verloopt, geeft de bijbehorende ID 404 terug.

  • Name
    reference_image_urls
    Type
    array
    Verplicht
    Description

    Een array van 1 tot 5 referentieafbeeldingen om te gebruiken voor de afbeeldingsbewerkingstaak. We ondersteunen momenteel de formaten .jpg, .jpeg en .png.

    Er zijn twee manieren om elke afbeelding aan te leveren:

    • Openbaar toegankelijke URL: Een URL die toegankelijk is vanaf het openbare internet.
    • Data URI: Een base64-gecodeerde data-URI van de afbeelding. Voorbeeld van een data-URI: data:image/jpeg;base64,<your base64-encoded image data>.
  • Name
    generate_multi_view
    Type
    boolean
    standaard false
    Description

    Wanneer ingesteld op true, wordt een afbeelding met meerdere aanzichten gegenereerd die het onderwerp vanuit meerdere hoeken toont.

    Wanneer generate_multi_view is ingesteld op true, kan de parameter aspect_ratio niet worden ingesteld.

  • Name
    aspect_ratio
    Type
    string
    standaard 1:1
    Description

    Geef de beeldverhouding van de uitvoerafbeelding op. Toegestane waarden zijn afhankelijk van het geselecteerde ai_model:

    • 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

    Beschikbare waarden:

    • 1:1: Vierkant formaat
    • 16:9: Breedbeeld liggend
    • 9:16: Breedbeeld staand
    • 4:3: Standaard liggend
    • 3:4: Standaard staand
    • 3:2: Liggend (alleen ondersteund door de GPT Image-modellen)
    • 2:3: Staand (alleen ondersteund door de GPT Image-modellen)
  • Name
    remove_background
    Type
    boolean
    standaard false
    Description

    Wanneer ingesteld op true, wordt de uitvoerafbeelding geretourneerd als een transparante RGBA PNG waarbij de achtergrond is verwijderd, zodat u het onderwerp op elke gewenste achtergrond kunt samenstellen.

Retourwaarden

De eigenschap result van de respons bevat de taak-id van de nieuw aangemaakte Image to Image-taak.

Foutmodi

  • Name
    400 - Bad Request
    Description

    Het verzoek was onaanvaardbaar. Veelvoorkomende oorzaken:

    • Ontbrekende parameter: Een verplichte parameter (bijv. ai_model, prompt) ontbreekt, of noch reference_image_urls noch input_task_id is opgegeven.
    • Ongeldige invoertaak: input_task_id moet verwijzen naar een SUCCEEDED Tekst naar afbeelding- of Afbeelding naar afbeelding-taak (inclusief meerdere aanzichten) die nog afbeeldingsuitvoer heeft. Een taak van een ander type, een taak die niet is geslaagd, of een taak waarvan alle afbeeldingen zijn verlopen, wordt geweigerd.
    • Ongeldig afbeeldingsformaat: Een of meer referentieafbeeldingen hebben geen ondersteund formaat.
    • Onbereikbare URL: Een of meer reference_image_urls konden niet worden gedownload.
    • Ongeldige parameter: aspect_ratio is niet een van de toegestane waarden voor het geselecteerde ai_model.
    • Conflict: generate_multi_view en aspect_ratio kunnen niet gelijktijdig worden gebruikt.
  • Name
    401 - Unauthorized
    Description

    Authenticatie is mislukt. Controleer uw API-sleutel.

  • Name
    402 - Payment Required
    Description

    Onvoldoende credits om deze taak uit te voeren.

  • Name
    404 - Not Found
    Description

    input_task_id verwijst niet naar een taak die eigendom is van uw account. Een taak die niet bestaat en een taak die aan een ander account toebehoort, geven dezelfde respons terug.

  • Name
    429 - Too Many Requests
    Description

    U heeft uw rate limit overschreden.

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

Een Afbeelding naar afbeelding-taak ophalen

Met deze endpoint kunt u een Afbeelding naar afbeelding-taak ophalen op basis van een geldige taak-id. Raadpleeg Het Afbeelding naar afbeelding-taakobject om te zien welke eigenschappen bij het Afbeelding naar afbeelding-taakobject horen.

Parameters

  • Name
    id
    Type
    path
    Description

    Unieke identifier voor de op te halen Afbeelding naar afbeelding-taak.

Retourwaarden

De response bevat het Afbeelding naar afbeelding-taakobject. Raadpleeg de sectie Het Afbeelding naar afbeelding-taakobject voor details.

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

Verwijder een Afbeelding naar afbeelding-taak

Deze endpoint verwijdert een Afbeelding naar afbeelding-taak permanent, inclusief alle bijbehorende afbeeldingen en gegevens. Deze actie is onomkeerbaar.

Padparameters

  • Name
    id
    Type
    path
    Description

    De ID van de Afbeelding naar afbeelding-taak die verwijderd moet worden.

Taakstatus

Een taak die nog PENDING is, wordt verwijderd en de credits die bij het aanmaken zijn verbruikt, worden terugbetaald.

Een taak die al IN_PROGRESS is, kan niet worden verwijderd: het verzoek wordt afgewezen met 409 Conflict en de taak blijft actief. Credits voor een taak die de worker al is gestart, zijn niet terugbetaalbaar, dus het verwijderen ervan tijdens de uitvoering zou u zowel de credits als het resultaat kosten. Wacht tot de taak SUCCEEDED, FAILED of CANCELED bereikt en verwijder deze dan.

Een taak in een eindstatus (SUCCEEDED, FAILED of CANCELED) wordt verwijderd zonder terugbetaling.

Retourwaarden

Retourneert 200 OK bij succes, of 409 Conflict wanneer de taak IN_PROGRESS is.

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

Lijst Afbeelding naar afbeelding taken opvragen

Deze endpoint stelt u in staat om een lijst met Afbeelding naar afbeelding taken op te vragen.

Parameters

  • Name
    page_num
    Type
    integer
    Description

    Paginanummer voor paginering. Begint bij en heeft als standaardwaarde 1.

  • Name
    page_size
    Type
    integer
    Description

    Limiet voor paginagrootte. Standaard 10 items. Maximaal toegestaan is 100 items.

  • Name
    sort_by
    Type
    string
    Description

    Veld om op te sorteren. Beschikbare waarden:

    • +created_at: Sorteer op aanmaaktijd in oplopende volgorde.
    • -created_at: Sorteer op aanmaaktijd in aflopende volgorde.

Retourneert

Retourneert een gepagineerde lijst van The Image to Image Task Objects.

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

Stream een Afbeelding naar afbeelding-taak

Deze endpoint streamt realtime updates voor een Afbeelding naar afbeelding-taak met behulp van Server-Sent Events (SSE).

Parameters

  • Name
    id
    Type
    path
    Description

    Unieke identificatie voor de Afbeelding naar afbeelding-taak die gestreamd moet worden.

Retourwaarden

Retourneert een stream van The Image to Image Task Objects als Server-Sent Events.

Voor taken met status PENDING of IN_PROGRESS bevat de responsestream alleen de noodzakelijke velden progress en status.

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

Het Image to Image Task-object is een werkeenheid die Meshy bijhoudt om een afbeelding te genereren op basis van referentieafbeeldingen en een tekstprompt-invoer. Het object heeft de volgende eigenschappen:

Properties

  • Name
    id
    Type
    string
    Description

    Unieke identificatie voor de taak. Hoewel we als implementatiedetail een k-sorteerbare UUID gebruiken voor taak-id's, mag je geen aannames doen over het formaat van de id.

  • Name
    type
    Type
    string
    Description

    Het type afbeeldingsgeneratietaak. Voor Image to Image-taken is dit altijd image-to-image.

  • Name
    ai_model
    Type
    string
    Description

    Het AI-model dat voor deze taak is gebruikt. Mogelijke waarden zijn nano-banana, nano-banana-2, nano-banana-pro, gpt-image-2, gpt-image-2-5-flare, of gpt-image-2-5-sunburst.

  • Name
    prompt
    Type
    string
    Description

    De tekstprompt die is gebruikt om de afbeeldingstransformatie te sturen.

  • Name
    status
    Type
    string
    Description

    Status van de taak. Mogelijke waarden zijn een van PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Voortgang van de taak. Als de taak nog niet is gestart, is deze eigenschap 0. Zodra de taak is geslaagd, wordt dit 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Tijdstempel van wanneer de taak is aangemaakt, in milliseconden.

    Een tijdstempel geeft het aantal milliseconden weer sinds 1 januari 1970 UTC, volgens de RFC 3339-standaard. Bijvoorbeeld, vrijdag 1 september 2023 12:00:00 PM GMT wordt weergegeven als 1693569600000. Dit geldt voor alle tijdstempels in de Meshy API.

  • Name
    started_at
    Type
    timestamp
    Description

    Tijdstempel van wanneer de taak is gestart, in milliseconden. Als de taak nog niet is gestart, is deze eigenschap 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Tijdstempel van wanneer de taak is voltooid, in milliseconden. Als de taak nog niet is voltooid, is deze eigenschap 0.

  • Name
    expires_at
    Type
    timestamp
    Description

    Tijdstempel van wanneer het taakresultaat verloopt, in milliseconden.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Het aantal voorafgaande taken.

    De waarde van dit veld is alleen betekenisvol als de taakstatus PENDING is.

  • Name
    image_urls
    Type
    array
    Description

    Een array van downloadbare URL's naar de gegenereerde afbeeldingen. Wanneer generate_multi_view is ingeschakeld, bevat deze array drie afbeeldings-URL's die verschillende kijkhoeken vertegenwoordigen. Anders bevat het één afbeeldings-URL.

  • Name
    task_error
    Type
    object
    Description

    Foutdetails voor mislukte taken. Zie Fouten voor de volledige referentie van het task_error-object.

  • Name
    consumed_credits
    Type
    integer
    Description

    Het aantal credits dat door deze taak is verbruikt. Aanwezig wanneer de taakstatus PENDING, IN_PROGRESS, of SUCCEEDED is. Geeft 0 terug voor FAILED-taken (credits worden bij mislukking terugbetaald).

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
}