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.

Deze endpoint genereert afbeeldingen. Als het doel een object is dat je vast kunt houden of printen — een sleutelhanger, koelkastmagneet, figuur, lamp of keycap op basis van een foto — gebruik dan de Creative Lab API's (prototypeafbeelding → 3D-model bouwen). Als het doel een 3D-model is van wat er op de afbeelding staat, gebruik dan Afbeelding naar 3D.

POST/openapi/v1/image-to-image

Een Image to Image-taak aanmaken

Met deze endpoint kun je een nieuwe Image to Image-taak aanmaken. Raadpleeg Het Image to Image-taakobject om te zien welke eigenschappen deel uitmaken van het Image to Image-taakobject.

De taak wordt op de achtergrond uitgevoerd. Voor een indicatie van de benodigde tijd, zie Verwerkingstijden.

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-2-lite: Lichte variant van nano-banana-2 (3 credits per afbeelding)
- nano-banana-pro: Pro-model met verbeterde kwaliteit (9 credits per afbeelding)
- gpt-image-2: OpenAI GPT Image 2, een high-fidelity model voor het bewerken van afbeeldingen (12 credits per afbeelding)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), een high-fidelity model voor het bewerken van afbeeldingen (12 credits per afbeelding)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), een high-fidelity model voor het bewerken van afbeeldingen (12 credits per afbeelding)
Name
prompt
Type
string
Verplicht
Description
Een tekstuele beschrijving van de transformatie of bewerking die je wilt toepassen op de referentieafbeeldingen.

Slechts één van input_task_id of reference_image_urls is vereist. 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 outputafbeeldingen gebruikt moeten worden als referentieafbeeldingen. Deze taak moet een van de volgende taken zijn: Tekst naar afbeelding of Afbeelding naar afbeelding, inclusief hun varianten met meerdere aanzichten. Daarnaast moet de taak zijn uitgevoerd via de API en de status SUCCEEDED hebben.
Alle outputafbeeldingen van de brontaak worden gebruikt. Een taak met één afbeelding levert 1 referentieafbeelding; een taak met meerdere aanzichten levert er één per gegenereerd aanzicht, waardoor één taak-ID meerdere van de 5 referentiesleuven kan vullen.
De brontaak moet zich nog binnen de asset-retentieperiode bevinden — zodra deze verloopt, geeft de 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, .png en .webp.
Maximale bestandsgrootte: 20 MB per afbeelding.
Er zijn twee manieren om elke afbeelding op te geven:
- Publiek toegankelijke URL: Een URL die toegankelijk is vanaf het publieke internet.
- Data URI: Een base64-gecodeerde data-URI van de afbeelding. Voorbeeld van een data-URI: data:image/jpeg;base64,<je base64-gecodeerde afbeeldingsdata>.

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 outputafbeelding op. Toegestane waarden zijn afhankelijk van het geselecteerde ai_model:
- nano-banana, nano-banana-2, nano-banana-2-lite, 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 outputafbeelding geretourneerd als een transparante RGBA PNG met de achtergrond verwijderd, zodat je het onderwerp op elke achtergrond kunt samenstellen.

Resultaten

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

Foutmodi

Name
400 - Bad Request
Description
Het verzoek was onacceptabel. Veelvoorkomende oorzaken:
- Ontbrekende parameter: Een vereiste parameter (bijv. ai_model, prompt) ontbreekt, of er is noch reference_image_urls noch input_task_id opgegeven.
- Ongeldige inputtaak: input_task_id moet verwijzen naar een SUCCEEDED Tekst naar afbeelding- of Afbeelding naar afbeelding-taak (inclusief meerdere aanzichten) die nog outputafbeeldingen heeft. Een taak van een ander type, een taak die niet geslaagd is, of een taak waarvan alle afbeeldingen zijn verlopen, wordt afgewezen.
- Ongeldig afbeeldingsformaat: Een of meer referentieafbeeldingen hebben een niet-ondersteund formaat.
- Onbereikbare URL: Een of meer reference_image_urls konden niet worden gedownload.
- Afbeelding te groot: Een of meer afbeeldingen in reference_image_urls overschrijden 20 MB.
- 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 tegelijkertijd worden gebruikt.
Name
401 - Unauthorized
Description
Authenticatie mislukt. Controleer je API-sleutel.
Name
402 - Payment Required
Description
Onvoldoende credits om deze taak uit te voeren.
Name
404 - Not Found
Description
De input_task_id verwijst niet naar een taak die eigendom is van jouw account. Een taak die niet bestaat en een taak die bij een ander account hoort, geven dezelfde response terug.
Name
429 - Too Many Requests
Description
Je hebt je 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=***"
  ]
}

Het 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:

Eigenschappen

Name
id
Type
string
Description
Unieke identifier 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-2-lite, 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 werd 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 het moment waarop de taak werd aangemaakt, in milliseconden.
Een tijdstempel geeft het aantal milliseconden weer dat is verstreken sinds 1 januari 1970 UTC, volgens de RFC 3339-standaard. Vrijdag 1 september 2023 12:00:00 PM GMT wordt bijvoorbeeld weergegeven als 1693569600000. Dit geldt voor alle tijdstempels in de Meshy API.
Name
started_at
Type
timestamp
Description
Tijdstempel van het moment waarop de taak werd gestart, in milliseconden. Als de taak nog niet is gestart, is deze eigenschap 0.
Name
finished_at
Type
timestamp
Description
Tijdstempel van het moment waarop de taak werd voltooid, in milliseconden. Als de taak nog niet is voltooid, is deze eigenschap 0.
Name
expires_at
Type
timestamp
Description
Tijdstempel van het moment waarop het taakresultaat verloopt, in milliseconden.
Name
preceding_tasks
Type
integer
Description
Het aantal voorgaande 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 een enkele 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. Retourneert 0 voor FAILED-taken (credits worden terugbetaald bij een mislukking).

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
}