Afbeelding naar afbeelding API

Bewerk en transformeer afbeeldingen binnen je eigen applicatie. Stuur referentieafbeeldingen en een tekstprompt, en de AI-modellen van Meshy genereren hieruit een nieuwe afbeelding.

Afbeelding naar afbeelding maakt afbeeldingen. Om een 3D-model te maken van wat er op een afbeelding staat, gebruik je Afbeelding naar 3D. Om een object te maken dat je vast kunt houden of printen vanaf een foto, gebruik je de Creative Lab API's. Deze maken een prototypeafbeelding en bouwen daarvan vervolgens een 3D-model, bijvoorbeeld een sleutelhanger, koelkastmagneet, figuur, lamp of keycap.

POST/openapi/v1/image-to-image

Create an Image to Image task

Maakt een Afbeelding naar afbeelding-taak. De taak wordt op de achtergrond uitgevoerd. Voor meer informatie over hoe lang een taak meestal duurt, zie Verwerkingstijden.

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

Parameters

Name
ai_model
Type
string
Verplicht
Description
Het AI-model dat de afbeelding genereert. Prijzen verschillen per model. Zie Prijzen.
Beschikbare waarden:
- nano-banana: het standaardmodel
- nano-banana-2: capabeler dan nano-banana
- nano-banana-2-lite: een lite-versie van nano-banana-2
- nano-banana-2-1: Nano Banana 2.1
- nano-banana-pro: het Pro-model, met hogere kwaliteit. Hiervoor is een Pro-abonnement of hoger vereist. Bij een lager abonnement retourneert het 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
Verplicht
Description
Tekst die de bewerking of transformatie beschrijft die op de referentieafbeeldingen moet worden toegepast.

Name
input_task_id
Type
string
Verplicht
Description
Vereist, tenzij je reference_image_urls meestuurt. Het ID van een Tekst naar afbeelding- of Afbeelding naar afbeelding-taak waarvan de afbeeldingen als referentie worden gebruikt, inclusief taken met meerdere aanzichten. De taak moet er een zijn die je met de API hebt aangemaakt en de status SUCCEEDED hebben.
Meshy gebruikt elke afbeelding die de taak heeft geproduceerd. Een taak met één afbeelding levert één referentieafbeelding, en een taak met meerdere aanzichten levert er één per aanzicht. Eén taak-ID kan dus meerdere van de vijf referentieplekken vullen.
De taak moet nog binnen de asset-retentieperiode vallen. Nadat deze is verlopen, retourneert het ID 404.

Name
reference_image_urls
Type
array
Verplicht
Description
Vereist, tenzij je input_task_id meestuurt. Eén tot vijf referentieafbeeldingen om te bewerken, elk een publieke URL of een Data URI, bijvoorbeeld data:image/jpeg;base64,<je base64-gecodeerde afbeeldingsgegevens>. Een lege array, of meer dan vijf afbeeldingen, retourneert 400. Als je beide meestuurt, gebruikt Meshy input_task_id.
Elke afbeelding moet een .jpg-, .jpeg-, .png- of .webp-bestand zijn van maximaal 20 MB, en minstens 32 pixels aan elke zijde.

Name
generate_multi_view
Type
boolean
standaard false
Description
Of er een afbeelding met meerdere aanzichten moet worden gegenereerd die het onderwerp vanuit verschillende hoeken toont. Als dit true is, kun je geen aspect_ratio meesturen. Als je beide meestuurt, retourneert het 400.
Name
aspect_ratio
Type
string
standaard 1:1
Description
De beeldverhouding van de uitvoerafbeelding. Welke waarden je kunt meesturen, hangt af van ai_model.
Beschikbare waarden:
- 1:1: vierkant
- 16:9: breedbeeld liggend
- 9:16: breedbeeld staand
- 4:3: standaard liggend
- 3:4: standaard staand
- 3:2: liggend, alleen GPT Image-modellen
- 2:3: staand, alleen GPT Image-modellen
De GPT Image-modellen zijn gpt-image-2, gpt-image-2-5-flare en gpt-image-2-5-sunburst. Bij een nano-banana-model retourneren 3:2 en 2:3 400.
Name
remove_background
Type
boolean
standaard false
Description
Of de achtergrond moet worden verwijderd. Als dit true is, retourneert Meshy de uitvoerafbeelding als een transparante RGBA PNG, zodat je het onderwerp op elke achtergrond kunt plaatsen.

Resultaten

Het veld result van het antwoord bevat het ID van de nieuwe Afbeelding naar afbeelding-taak.

Foutmodi

Name
400 - Bad Request
Description
De aanvraag kan niet worden uitgevoerd. Het foutbericht geeft aan welk probleem is gevonden. Bijvoorbeeld:
- Ontbrekende parameter: Een vereiste parameter, zoals ai_model of prompt, ontbreekt, of er is noch reference_image_urls noch input_task_id meegestuurd.
- Ongeldige invoertaak: input_task_id verwijst niet naar een bruikbare taak. Het moet een SUCCEEDED Tekst naar afbeelding- of Afbeelding naar afbeelding-taak zijn, inclusief meerdere aanzichten, die nog afbeeldingsresultaten heeft. Meshy wijst een taak van een ander type, een taak die niet is geslaagd, en een taak waarvan alle afbeeldingen zijn verlopen af.
- Ongeldig afbeeldingsformaat: Een of meer referentieafbeeldingen hebben geen ondersteund formaat.
- Onbereikbare URL: Meshy kan een of meer reference_image_urls-afbeeldingen niet downloaden.
- Afbeelding te groot: Een of meer reference_image_urls-afbeeldingen zijn groter dan 20 MB.
- Afbeelding te klein: Een of meer reference_image_urls-afbeeldingen hebben een zijde korter dan 32 pixels.
- Ongeldige parameter: aspect_ratio is geen van de waarden die het geselecteerde ai_model ondersteunt.
- Conflict: De aanvraag stuurt aspect_ratio mee met generate_multi_view: true.
Corrigeer de aanvraag en stuur deze opnieuw. Zie Fouten.
Name
401 - Unauthorized
Description
De API-sleutel ontbreekt of is ongeldig. Controleer de Authorization-header.
Name
402 - Payment Required
Description
Het account kan deze taak niet uitvoeren. Bijvoorbeeld:
- Gratis abonnement: Voor het aanmaken van een taak is een betaald abonnement vereist. Upgrade je abonnement in je abonnementsinstellingen en probeer het opnieuw.
- Onvoldoende credits: Het account heeft niet genoeg credits voor deze taak, of het account heeft een creditlimiet bereikt.
- Abonnement vereist: De aanvraag gebruikt nano-banana-pro bij een abonnement lager dan Pro.
Controleer je creditsaldo en abonnement en probeer het opnieuw.
Name
404 - Not Found
Description
input_task_id komt niet overeen met een taak in je account. Een taak die niet bestaat en een taak die bij een ander account hoort, geven dezelfde reactie terug. Controleer het ID.
Name
429 - Too Many Requests
Description
Je hebt je rate limit overschreden. Wacht en probeer het opnieuw. Zie Rate limits.

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

Een Afbeelding naar afbeelding-taak ophalen

Retourneert een Afbeelding naar afbeelding-taak op basis van de 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=***"
  ]
}

Parameters

Name
id
Type
path
Description
De taak-ID uit het antwoord van het aanmaken.

Retourneert

Het Afbeelding naar afbeelding-taakobject.

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

Een Image to Image-taak verwijderen

Verwijdert een Afbeelding naar afbeelding-taak permanent, inclusief de bijbehorende afbeeldingen en gegevens. Een verwijdering kan niet ongedaan worden gemaakt.

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

Padparameters

Name
id
Type
path
Description
De ID van de te verwijderen taak.

Taakstatus

Het verwijderen van een PENDING-taak restitueert de credits die werden gebruikt bij het aanmaken ervan.

Een IN_PROGRESS-taak kan niet worden verwijderd. Het verzoek geeft 409 Conflict terug, en de taak blijft doorlopen. Meshy restitueert geen credits voor een taak die al is gestart, dus het verwijderen ervan zou je zowel de credits als het resultaat kosten. Wacht tot deze de status SUCCEEDED, FAILED of CANCELED bereikt, en verwijder hem dan.

Het verwijderen van een taak met een definitieve status (SUCCEEDED, FAILED of CANCELED) restitueert de bijbehorende credits niet.

Resultaten

200 OK wanneer de taak is verwijderd, of 409 Conflict wanneer de taak IN_PROGRESS is.

GET/openapi/v1/image-to-image

Lijst van Afbeelding naar afbeelding-taken

Geeft een lijst van uw Afbeelding naar afbeelding- en Tekst naar afbeelding-taken terug. Het veld type van elke taak geeft aan om welke van de twee het gaat.

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

Parameters

Name
page_num
Type
integer
Description
Het paginanummer dat moet worden teruggegeven. Begint bij en standaard 1.
Name
page_size
Type
integer
Description
Het aantal taken per pagina, tot 100. Standaard 10.
Name
sort_by
Type
string
Description
De sorteervolgorde.
Beschikbare waarden:
- +created_at: oudste eerst
- -created_at: nieuwste eerst

Retourneert

Een gepagineerde lijst met taakobjecten, in hetzelfde formaat als het Afbeelding naar afbeelding-taakobject.

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

Een Afbeelding naar afbeelding-taak streamen

Streamt de updates van een Afbeelding naar afbeelding-taak als Server-Sent Events (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=***"
  ]
}

Parameters

Name
id
Type
path
Description
De taak-ID uit het aanmaakantwoord.

Retourwaarden

Een stream van Afbeelding naar afbeelding-taakobjecten als Server-Sent Events.

Elke gebeurtenis bevat het volledige taakobject, in dezelfde vorm als het antwoord van de Get-endpoint. Zolang de taak PENDING of IN_PROGRESS is, hebben de resultaatvelden nog geen waarden.

Het Image to Image-taakobject

Een Image to Image-taakobject beschrijft één afbeelding die is gegenereerd op basis van referentieafbeeldingen en een tekstprompt. Het bevat de status, de progress en de afbeeldingen zodra de taak slaagt.

Eigenschappen

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
De taak-ID. Behandel dit als een ondoorzichtige tekenreeks en vertrouw niet op het formaat ervan.
Name
type
Type
string
Description
Het taaktype, altijd image-to-image.
Name
ai_model
Type
string
Description
Het AI-model dat de taak heeft gebruikt.
Beschikbare waarden:
- 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
Name
prompt
Type
string
Description
De tekstprompt die de bewerking heeft gestuurd.
Name
status
Type
string
Description
De taakstatus, een van PENDING, IN_PROGRESS, SUCCEEDED, FAILED, of CANCELED.
Name
progress
Type
integer
Description
Hoeveel van de taak is voltooid, als percentage. Dit is 0 totdat de taak start en 100 wanneer deze slaagt.
Name
created_at
Type
timestamp
Description
Tijdstip waarop de taak is aangemaakt, in Unix-milliseconden.
Name
started_at
Type
timestamp
Description
Tijdstip waarop de taak is gestart, in Unix-milliseconden. Afwezig totdat de taak start.
Name
finished_at
Type
timestamp
Description
Tijdstip waarop de taak is voltooid, in Unix-milliseconden. Afwezig totdat de taak is voltooid.
Name
expires_at
Type
timestamp
Description
Tijdstip waarop de resultaten van de taak verlopen, in Unix-milliseconden. Afwezig totdat de taak is voltooid.
Name
preceding_tasks
Type
integer
Description
Het aantal taken dat vóór deze taak in de wachtrij staat. De waarde is alleen relevant zolang de taak PENDING is. Het veld wordt weggelaten wanneer de waarde 0 is.
Name
image_urls
Type
array
Description
Download-URL's voor de gegenereerde afbeeldingen. Met generate_multi_view: true bevat dit één URL per aanzicht, meestal drie. Als Meshy niet elk aanzicht kan scheiden, worden er minder geretourneerd en slaagt de taak nog steeds. Anders bevat het één URL.
Name
task_error
Type
object
Description
De foutgegevens wanneer de taak mislukt. Dit is null tenzij de status FAILED is. Zie Fouten.
Name
consumed_credits
Type
integer
Description
Het aantal credits dat de taak heeft gebruikt. Aanwezig wanneer de status PENDING, IN_PROGRESS, of SUCCEEDED is. Dit is 0 voor een FAILED-taak, omdat Meshy de credits terugbetaalt wanneer een taak mislukt.