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 behulp van onze krachtige AI-modellen.

Deze endpoint produceert afbeeldingen. Als het doel een object is dat je kunt vasthouden of printen — een sleutelhanger, koelkastmagneet, figuur, lamp of keycap op basis van een foto — gebruik dan de Creative Lab API's (prototype-afbeelding → 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 kun je een nieuwe Tekst naar afbeelding-taak aanmaken. Raadpleeg Het Text to Image Task Object om te zien welke eigenschappen deel uitmaken van het Text to Image task object.

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

Parameters

Name
ai_model
Type
string
Verplicht
Description
ID van het model dat gebruikt wordt voor het genereren van de afbeelding.
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 nauwkeurig afbeeldingsmodel (9 credits per afbeelding)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), een zeer nauwkeurig afbeeldingsmodel (9 credits per afbeelding)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), een zeer nauwkeurig afbeeldingsmodel (9 credits per afbeelding)
Name
prompt
Type
string
Verplicht
Description
Een tekstbeschrijving van de afbeelding die je wilt genereren. Wees beschrijvend voor de beste resultaten.
Name
generate_multi_view
Type
boolean
standaard false
Description
Indien ingesteld op true, wordt 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. Indien weggelaten, wordt de afbeelding gegenereerd zonder vooraf ingestelde poses.
Beschikbare waarden: a-pose, t-pose
Name
aspect_ratio
Type
string
standaard 1:1
Description
Geef de beeldverhouding van de gegenereerde afbeelding op. Toegestane waarden zijn afhankelijk van het gekozen 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
Indien ingesteld op true, wordt de gegenereerde afbeelding geretourneerd als een transparante RGBA PNG met de achtergrond verwijderd, zodat je het onderwerp op elke gewenste achtergrond kunt plaatsen.

Retourwaarden

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

Foutmodi

Name
400 - Bad Request
Description
Het verzoek was onacceptabel. Veelvoorkomende oorzaken:
- Ontbrekende parameter: Een verplichte parameter (bijv. ai_model, prompt) ontbreekt.
- Ongeldige parameter: ai_model of aspect_ratio is geen van de toegestane waarden.
- Conflict: generate_multi_view en aspect_ratio kunnen niet gelijktijdig 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
429 - Too Many Requests
Description
Je hebt je 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

Retrieve a Text to Image Task

Deze endpoint stelt u in staat om een Tekst naar afbeelding-taak op te halen op basis van een geldige taak-id. Raadpleeg Het Tekst naar afbeelding-taakobject om te zien welke eigenschappen zijn opgenomen in het Tekst naar afbeelding-taakobject.

Parameters

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

Retourneert

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 waaraan de worker al is begonnen, zijn niet terugbetaalbaar, dus het verwijderen ervan tijdens het uitvoeren zou u zowel de credits als het resultaat kosten. Wacht tot deze de status SUCCEEDED, FAILED of CANCELED bereikt en verwijder deze dan.

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

Retourneert

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

Deze endpoint stelt u in staat om een lijst met Tekst naar afbeelding-taken op te halen.

Parameters

Name
page_num
Type
integer
Description
Paginanummer voor paginering. Begint bij en staat standaard op 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.

Returns

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 real-time updates voor een Tekst naar afbeelding-taak via Server-Sent Events (SSE).

Parameters

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

Retourneert

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

Het Text to Image-taakobject

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

Eigenschappen

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 de indeling 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 tekst prompt die werd 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 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 werd aangemaakt, in milliseconden.
Een tijdstempel vertegenwoordigt het aantal milliseconden dat is verstreken 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 werd 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 werd 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 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 enkele afbeeldings-URL.
Name
task_error
Type
object
Description
Foutdetails voor mislukte taken. Zie Fouten voor de volledige task_error-objectreferentie.
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 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
}