Text till bild-API

Generera bilder från en text-prompt med Meshys AI-modeller.

Text till bild skapar bilder. För att skapa en 3D-modell av det som finns i en bild, använd Bild till 3D. För att skapa ett objekt du kan hålla i handen eller skriva ut från ett foto, använd Creative Lab-API:erna. De skapar en prototypbild och bygger sedan en 3D-modell utifrån den, till exempel en nyckelring, kylskåpsmagnet, figur, lampa eller keycap.

POST/openapi/v1/text-to-image

Skapa en Text till bild-uppgift

Skapar en Text till bild-uppgift. Uppgiften körs i bakgrunden. För hur lång tid en uppgift vanligtvis tar, se Bearbetningstider.

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

Parametrar

Name
ai_model
Type
string
Obligatorisk
Description
AI-modellen som genererar bilden. Priserna skiljer sig åt mellan modeller. För priser, se Priser.
Tillgängliga värden:
- nano-banana: standardmodellen
- nano-banana-2: mer kapabel än nano-banana
- nano-banana-2-lite: en lite-version av nano-banana-2
- nano-banana-2-1: Nano Banana 2.1
- nano-banana-pro: Pro-modellen, med högre kvalitet. Kräver ett Pro-abonnemang eller högre. På ett lägre abonnemang returneras 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
Obligatorisk
Description
Text som beskriver bilden som ska genereras. En detaljerad beskrivning ger bättre resultat.
Name
generate_multi_view
Type
boolean
standard false
Description
Om en flervybild ska genereras som visar motivet från flera vinklar. När den är true kan du inte skicka aspect_ratio. Att skicka båda returnerar 400.
Name
pose_mode
Type
string
Description
Posen för en karaktär, a-pose eller t-pose. Utelämna den för ingen pose.
Hur en pose fungerar beror på ai_model:
- nano-banana-2, nano-banana-2-lite och nano-banana-2-1: Meshy behåller modellen du valde. Bilden är alltid 3:4, och Meshy ignorerar aspect_ratio.
- nano-banana och nano-banana-pro: Meshy genererar bilden med nano-banana-pro, så uppgiftens ai_model läses tillbaka som nano-banana-pro. Detta kräver ett Pro-abonnemang eller högre. Bilden är alltid 3:4, och Meshy ignorerar aspect_ratio.
- GPT Image-modellerna (gpt-image-2, gpt-image-2-5-flare och gpt-image-2-5-sunburst): Meshy behåller modellen du valde och din aspect_ratio.
Name
aspect_ratio
Type
string
standard 1:1
Description
Bildens form. Värdena du kan skicka beror på ai_model.
Tillgängliga värden:
- 1:1: kvadratisk
- 16:9: bredbildsliggande
- 9:16: bredbildsstående
- 4:3: standardliggande
- 3:4: standardstående
- 3:2: liggande, endast GPT Image-modeller
- 2:3: stående, endast GPT Image-modeller
nano-banana-modellerna (nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-2-1 och nano-banana-pro) returnerar 400 för 3:2 och 2:3.
Name
remove_background
Type
boolean
standard false
Description
Om bildens bakgrund ska tas bort. true returnerar en transparent RGBA-PNG, så att du kan placera motivet mot vilken bakgrund som helst.

Returnerar

Svarets result-fält innehåller ID:t för den nya Text till bild-uppgiften.

Felscenarier

Name
400 - Bad Request
Description
Begäran kan inte köras. Felmeddelandet anger vilket problem som hittades. Till exempel:
- Saknad parameter: En obligatorisk parameter, till exempel ai_model eller prompt, saknas.
- Ogiltig parameter: ai_model eller aspect_ratio är inte ett av de tillåtna värdena.
- Konflikt: aspect_ratio skickades tillsammans med generate_multi_view: true.
Åtgärda begäran och skicka den sedan igen. Se Fel.
Name
401 - Unauthorized
Description
API-nyckeln saknas eller är ogiltig. Kontrollera Authorization-headern.
Name
402 - Payment Required
Description
Kontot kan inte köra den här uppgiften. Till exempel:
- Gratisabonnemang: Att skapa en uppgift kräver ett betalt abonnemang. Uppgradera ditt abonnemang i dina prenumerationsinställningar och försök sedan igen.
- Otillräckliga credits: Kontot har inte tillräckligt med credits för den här uppgiften (Insufficient funds), eller kontot har nått en credits-gräns.
- Abonnemang krävs: Begäran använder nano-banana-pro, eller pose_mode med nano-banana, på ett abonnemang lägre än Pro (Only Pro and above users can use nano-banana-pro, eller Only Pro and above users can use A/T pose feature (requires nano-banana-pro)).
Kontrollera ditt credits-saldo och abonnemang och försök sedan igen.
Name
429 - Too Many Requests
Description
Du överskred din hastighetsgräns. Vänta och försök sedan igen. Se Hastighetsgränser.

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

Hämta en Text till bild-uppgift

Returnerar en Text till bild-uppgift baserat på dess 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=***"
  ]
}

Parametrar

Name
id
Type
path
Description
Uppgifts-ID:t från svaret vid skapandet.

Returnerar

Objektet för Text till bild-uppgiften.

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

Ta bort en Text till bild-uppgift

Tar bort en Text till bild-uppgift permanent, inklusive dess bilder och data. Du kan inte ångra en borttagning.

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

Sökvägsparametrar

Name
id
Type
path
Description
ID:t för uppgiften som ska tas bort.

Uppgiftsstatus

Om du tar bort en PENDING-uppgift återbetalas de credits som användes när du skapade den.

En IN_PROGRESS-uppgift kan inte tas bort. Begäran returnerar 409 Conflict, och uppgiften fortsätter att köras. Meshy återbetalar inte en uppgift som har påbörjats, så att ta bort den skulle kosta dig både krediterna och resultatet. Vänta tills den når SUCCEEDED, FAILED eller CANCELED, ta sedan bort den.

Att ta bort en uppgift med en slutgiltig status (SUCCEEDED, FAILED eller CANCELED) återbetalar inte dess credits.

Returnerar

200 OK när uppgiften har tagits bort, eller 409 Conflict när uppgiften är IN_PROGRESS.

GET/openapi/v1/text-to-image

Lista Text till bild-uppgifter

Returnerar en lista över dina Text till bild- och Bild till bild-uppgifter. Varje uppgifts type-fält anger vilken av de två det är.

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

Parametrar

Name
page_num
Type
integer
Description
Sidnumret som ska returneras. Börjar på och har som standardvärde 1.
Name
page_size
Type
integer
Description
Antalet uppgifter per sida, upp till 100. Standardvärdet är 10.
Name
sort_by
Type
string
Description
Sorteringsordningen.
Tillgängliga värden:
- +created_at: äldsta först
- -created_at: nyaste först

Returnerar

En paginerad lista med uppgiftsobjekt, i samma format som Text till bild-uppgiftsobjektet.

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

Strömma en Text till bild-uppgift

Strömmar uppdateringar för en Text till bild-uppgift som 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=***"
  ]
}

Parametrar

Name
id
Type
path
Description
Uppgifts-ID från create-svaret.

Returnerar

En ström av Text till bild-uppgiftsobjekt som Server-Sent Events.

Varje event innehåller hela uppgiftsobjektet, i samma format som Get-endpointen returnerar. Medan uppgiften är PENDING eller IN_PROGRESS har dess resultatfält ännu inga värden.

Objektet för Text till bild-uppgiften

Ett Text till bild-uppgiftsobjekt beskriver en bildgenerering från en textprompt. Det innehåller status, progress och bild-URL:er när uppgiften lyckas.

Egenskaper

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
Uppgifts-ID:t. Behandla det som en ogenomskinlig sträng och förlita dig inte på dess format.
Name
type
Type
string
Description
Uppgiftstypen, alltid text-to-image.
Name
ai_model
Type
string
Description
AI-modellen som uppgiften använde.
Möjliga värden:
- 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
Textprompten du skapade uppgiften med.
Name
status
Type
string
Description
Uppgiftens status, en av PENDING, IN_PROGRESS, SUCCEEDED, FAILED eller CANCELED.
Name
progress
Type
integer
Description
Hur mycket av uppgiften som är klar, i procent. Den är 0 tills uppgiften startar och 100 när den lyckas.
Name
created_at
Type
timestamp
Description
Tidpunkten då uppgiften skapades, i Unix-millisekunder.
Name
started_at
Type
timestamp
Description
Tidpunkten då uppgiften startade, i Unix-millisekunder. Saknas tills uppgiften startar.
Name
finished_at
Type
timestamp
Description
Tidpunkten då uppgiften avslutades, i Unix-millisekunder. Saknas tills uppgiften avslutas.
Name
expires_at
Type
timestamp
Description
Tidpunkten då uppgiftens resultat upphör att gälla, i Unix-millisekunder. Saknas tills uppgiften avslutas.
Name
preceding_tasks
Type
integer
Description
Antalet uppgifter som ligger före denna i kön. Värdet är endast meningsfullt medan uppgiften är PENDING. Fältet utelämnas när värdet är 0.
Name
image_urls
Type
array
Description
Nedladdnings-URL:er för de genererade bilderna. Med generate_multi_view: true innehåller arrayen en URL per vy, vanligtvis tre. Om Meshy inte kan separera varje vy returneras färre, och uppgiften lyckas ändå. Annars innehåller den en URL.
Name
task_error
Type
object
Description
Felinformationen när uppgiften misslyckas. Den är null om inte statusen är FAILED. Se Fel.
Name
consumed_credits
Type
integer
Description
Antalet credits som uppgiften använde. Finns när statusen är PENDING, IN_PROGRESS eller SUCCEEDED. Den är 0 för en FAILED-uppgift, eftersom Meshy återbetalar credits när en uppgift misslyckas.