Tekst naar afbeelding API

Tekst naar afbeelding API is een functie waarmee je de AI-beeldgeneratiemogelijkheden van Meshy kunt integreren in je eigen applicatie. Genereer afbeeldingen van hoge kwaliteit op basis van tekstprompts met onze krachtige AI-modellen.

Deze endpoint produceert 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/text-to-image

Een Tekst naar afbeelding-taak aanmaken

Met deze endpoint kunt u een nieuwe Tekst naar afbeelding-taak aanmaken. Raadpleeg Het Tekst naar afbeelding-taakobject om te zien welke eigenschappen deel uitmaken van het Tekst naar afbeelding-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 moet worden gebruikt voor het genereren van afbeeldingen.
Beschikbare waarden:
- nano-banana: Standaardmodel (3 credits per afbeelding)
- nano-banana-2: Uitgebalanceerd model met sterkere mogelijkheden dan het standaardmodel (6 credits per afbeelding)
- nano-banana-2-lite: Lite-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 zeer hoogwaardig afbeeldingsmodel (9 credits per afbeelding)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), een zeer hoogwaardig afbeeldingsmodel (9 credits per afbeelding)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), een zeer hoogwaardig afbeeldingsmodel (9 credits per afbeelding)
Name
prompt
Type
string
Verplicht
Description
Een tekstbeschrijving van de afbeelding die u wilt genereren. Wees beschrijvend voor de beste resultaten.
Name
generate_multi_view
Type
boolean
standaard false
Description
Wanneer ingesteld op true, wordt er een afbeelding met meerdere aanzichten gegenereerd die het onderwerp vanuit meerdere hoeken toont.
Wanneer generate_multi_view op true staat, kan de parameter aspect_ratio niet worden ingesteld.
Name
pose_mode
Type
string
Description
Geef de pose_mode op voor het genereren van personages. Wanneer dit wordt weggelaten, wordt de afbeelding gegenereerd zonder vooraf ingestelde poses.
Beschikbare waarden: a-pose, t-pose
Bij nano-banana, nano-banana-2, nano-banana-2-lite en nano-banana-pro zorgt het instellen van pose_mode ervoor dat de beeldverhouding van de output vastgezet wordt op 3:4 en wordt elke verzonden aspect_ratio genegeerd. nano-banana-2 en nano-banana-2-lite behouden het aangevraagde model. Bij nano-banana of nano-banana-pro wordt een afbeelding met pose gegenereerd door nano-banana-pro (de ai_model van de taak wordt teruggelezen als nano-banana-pro), waarvoor een Pro-abonnement of hoger vereist is. De GPT Image-modellen (gpt-image-2, gpt-image-2-5-flare, gpt-image-2-5-sunburst) behouden het aangevraagde model en de aangevraagde aspect_ratio.
Name
aspect_ratio
Type
string
standaard 1:1
Description
Geef de beeldverhouding op van de gegenereerde afbeelding. 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 gegenereerde afbeelding geretourneerd als een transparante RGBA PNG met de achtergrond verwijderd, zodat u het onderwerp op elke gewenste achtergrond kunt plaatsen.

Resultaat

De result-eigenschap van de response bevat de taak-id van de zojuist aangemaakte Tekst naar afbeelding-taak.

Foutmodi

Name
400 - Bad Request
Description
Het verzoek was onaanvaardbaar. Veelvoorkomende oorzaken:
- Ontbrekende parameter: Een vereiste parameter (bijv. ai_model, prompt) ontbreekt.
- Ongeldige parameter: ai_model of aspect_ratio bevat niet een van de toegestane waarden.
- 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
Veelvoorkomende oorzaken:
- Onvoldoende credits: Uw account heeft niet genoeg credits om deze taak uit te voeren (Insufficient funds).
- Abonnement vereist: nano-banana-pro, of pose_mode met nano-banana, vereist een Pro-abonnement of hoger (Only Pro and above users can use nano-banana-pro, of Only Pro and above users can use A/T pose feature (requires nano-banana-pro)).
Name
429 - Too Many Requests
Description
U heeft uw rate limit overschreden.

Request

POST

/openapi/v1/text-to-image

# Generate an image from a text prompt
curl https://api.meshy.ai/openapi/v1/text-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "A majestic dragon soaring through clouds at sunset",
    "aspect_ratio": "16:9"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

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

Een Tekst naar afbeelding-taak ophalen

Met deze endpoint kunt u een Tekst naar afbeelding-taak ophalen aan de hand van een geldig id van de taak. Raadpleeg Het Tekst naar afbeelding-taakobject om te zien welke eigenschappen bij het Tekst naar afbeelding-taakobject horen.

Parameters

Name
id
Type
path
Description
Unieke identificatie voor de op te halen Tekst naar afbeelding-taak.

Retourwaarden

Het antwoord bevat het Tekst naar afbeelding-taakobject. Raadpleeg de sectie Het Tekst naar afbeelding-taakobject voor details.

Request

GET

/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "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/text-to-image/:id

Een Tekst naar afbeelding-taak verwijderen

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

Padparameters

Name
id
Type
path
Description
De ID van de Tekst 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 doorlopen. Credits voor een taak waarmee de worker al is begonnen, zijn niet terugbetaalbaar, dus het verwijderen ervan halverwege 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/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/text-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/text-to-image

Lijst van Tekst naar afbeelding-taken

Met deze endpoint kunt u een lijst van Tekst naar afbeelding-taken ophalen.

Parameters

Name
page_num
Type
integer
Description
Paginanummer voor paginering. Begint bij en standaard is 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 De Tekst naar afbeelding-taakobjecten.

Request

GET

/openapi/v1/text-to-image

curl https://api.meshy.ai/openapi/v1/text-to-image?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-image",
    "ai_model": "nano-banana",
    "prompt": "A majestic dragon soaring through clouds at sunset",
    "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/text-to-image/:id/stream

Stream een Tekst naar afbeelding-taak

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

Parameters

Name
id
Type
path
Description
Unieke identifier voor de Tekst naar afbeelding-taak die gestreamd moet worden.

Returns

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

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

Request

GET

/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/text-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": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "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 Text to Image Task Object

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

Properties

Name
id
Type
string
Description
Unieke identifier voor de taak. Hoewel we een k-sorteerbare UUID gebruiken voor taak-id's als implementatiedetail, mag je geen aannames doen over het formaat van de id.
Name
type
Type
string
Description
Het type afbeeldingsgeneratietaak. Voor Text to Image-taken is dit altijd text-to-image.
Name
ai_model
Type
string
Description
Het AI-model dat voor deze taak wordt 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 is gebruikt om de afbeelding te genereren.
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 (progress) 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 vertegenwoordigt het aantal milliseconden 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 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 resultaat van de taak verloopt, in milliseconden.
Name
preceding_tasks
Type
integer
Description
Het aantal voorgaande taken.
De waarde van dit veld is alleen relevant 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 terugbetaald bij een mislukking).

Example Text to Image Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "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
}