Tekst naar afbeelding API

Genereer afbeeldingen vanuit een tekstprompt met de AI-modellen van Meshy.

Tekst naar afbeelding maakt afbeeldingen. Om een 3D-model te maken van wat er in een afbeelding staat, gebruik je Afbeelding naar 3D. Om een object te maken dat je kunt vasthouden of printen vanaf een foto, gebruik je de Creative Lab APIs. Deze maken een prototype-afbeelding en bouwen daar vervolgens een 3D-model van, bijvoorbeeld een sleutelhanger, koelkastmagneet, figuur, lamp of keycap.

POST/openapi/v1/text-to-image

Een Tekst naar afbeelding-taak maken

Maakt een Tekst naar afbeelding-taak. De taak wordt op de achtergrond uitgevoerd. Voor hoe lang een taak gewoonlijk duurt, zie Verwerkingstijden.

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

Parameters

Name
ai_model
Type
string
Verplicht
Description
Het AI-model dat de afbeelding genereert. Prijzen verschillen per model. Voor prijzen, 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. Vereist een Pro-abonnement of hoger. Bij een lager abonnement wordt 402 teruggegeven.
- 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 te genereren afbeelding beschrijft. Een gedetailleerde beschrijving geeft betere resultaten.
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 aspect_ratio niet meesturen. Als je beide verstuurt, wordt 400 teruggegeven.
Name
pose_mode
Type
string
Description
De pose voor een personage, a-pose of t-pose. Laat dit weg voor geen pose.
Hoe een pose werkt, hangt af van ai_model:
- nano-banana-2, nano-banana-2-lite en nano-banana-2-1: Meshy behoudt het model dat je hebt gekozen. De afbeelding is altijd 3:4, en Meshy negeert aspect_ratio.
- nano-banana en nano-banana-pro: Meshy genereert de afbeelding met nano-banana-pro, waardoor de ai_model van de taak wordt teruggelezen als nano-banana-pro. Dit vereist een Pro-abonnement of hoger. De afbeelding is altijd 3:4, en Meshy negeert aspect_ratio.
- De GPT Image-modellen (gpt-image-2, gpt-image-2-5-flare en gpt-image-2-5-sunburst): Meshy behoudt het model dat je hebt gekozen en je aspect_ratio.
Name
aspect_ratio
Type
string
standaard 1:1
Description
De vorm van de afbeelding. De waarden die je kunt meesturen hangen 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 nano-banana-modellen (nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-2-1 en nano-banana-pro) geven 400 terug voor 3:2 en 2:3.
Name
remove_background
Type
boolean
standaard false
Description
Of de achtergrond van de afbeelding moet worden verwijderd. true geeft een transparante RGBA PNG terug, zodat je het onderwerp op elke achtergrond kunt plaatsen.

Retourwaarden

Het veld result van de respons bevat de ID van de nieuwe Tekst naar afbeelding-taak.

Foutmodi

Name
400 - Bad Request
Description
De aanvraag kan niet worden uitgevoerd. Het foutbericht geeft aan welk probleem er is gevonden. Bijvoorbeeld:
- Ontbrekende parameter: Een vereiste parameter, zoals ai_model of prompt, ontbreekt.
- Ongeldige parameter: ai_model of aspect_ratio is niet een van de toegestane waarden.
- Conflict: aspect_ratio werd meegestuurd met generate_multi_view: true.
Corrigeer de aanvraag en verstuur 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 maken 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 (Insufficient funds), of het account heeft een creditlimiet bereikt.
- Abonnement vereist: De aanvraag gebruikt nano-banana-pro, of pose_mode met nano-banana, op een abonnement lager dan Pro (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)).
Controleer je creditsaldo en abonnement, en probeer het opnieuw.
Name
429 - Too Many Requests
Description
Je hebt je rate limit overschreden. Wacht en probeer het opnieuw. Zie Rate limits.

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

Een Text to Image-taak ophalen

Retourneert een Tekst naar afbeelding-taak aan de hand van de ID.

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

Parameters

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

Retourneert

Het Tekst naar afbeelding-taakobject.

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

Een Tekst naar afbeelding-taak verwijderen

Verwijdert een Tekst naar afbeelding-taak permanent, inclusief de bijbehorende afbeeldingen en gegevens. Je kunt een verwijdering niet ongedaan maken.

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 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 zijn gebruikt bij het aanmaken ervan.

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

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

Resultaten

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

GET/openapi/v1/text-to-image

Tekst naar afbeelding-taken weergeven

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

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

Parameters

Name
page_num
Type
integer
Description
Het paginanummer dat moet worden geretourneerd. 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 van taakobjecten, in hetzelfde formaat als het Tekst naar afbeelding-taakobject.

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

Stream een Tekst naar afbeelding-taak

Streamt de updates van een Tekst naar afbeelding-taak als Server-Sent Events (SSE).

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

Parameters

Name
id
Type
path
Description
De taak-ID uit de create-respons.

Retourneert

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

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

Het Text to Image-taakobject

Een Text to Image-taakobject beschrijft één afbeeldingsgeneratie op basis van een tekstprompt. Het bevat de status, de progress en de afbeeldings-URL's wanneer de taak slaagt.

Eigenschappen

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,
  "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 string en vertrouw niet op het formaat ervan.
Name
type
Type
string
Description
Het taaktype, altijd text-to-image.
Name
ai_model
Type
string
Description
Het AI-model dat de taak gebruikte.
Mogelijke 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 waarmee je de taak hebt aangemaakt.
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. Het is 0 tot 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 tot de taak start.
Name
finished_at
Type
timestamp
Description
Tijdstip waarop de taak is beëindigd, in Unix-milliseconden. Afwezig tot de taak eindigt.
Name
expires_at
Type
timestamp
Description
Tijdstip waarop de resultaten van de taak verlopen, in Unix-milliseconden. Afwezig tot de taak eindigt.
Name
preceding_tasks
Type
integer
Description
Het aantal taken dat voor deze taak in de wachtrij staat. De waarde is alleen betekenisvol 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 de array één URL per aanzicht, meestal drie. Als Meshy niet elk aanzicht kan scheiden, retourneert het er minder en slaagt de taak alsnog. Anders bevat het één URL.
Name
task_error
Type
object
Description
De foutdetails 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. Het is 0 voor een FAILED-taak, omdat Meshy de credits terugbetaalt wanneer een taak mislukt.