Text to Image API

Vytvářejte obrázky z textového promptu pomocí AI modelů Meshy.

Text na obrázek vytváří obrázky. Pokud chcete vytvořit 3D model toho, co je na obrázku, použijte Obrázek na 3D. Pokud chcete z fotografie vytvořit objekt, který můžete držet v ruce nebo vytisknout, použijte Creative Lab APIs. Ty nejprve vytvoří prototypový obrázek a poté z něj sestaví 3D model, například klíčenku, magnet na lednici, figurku, lampu nebo keycap.

POST/openapi/v1/text-to-image

Vytvoření úlohy Text na obrázek

Vytvoří úlohu Text na obrázek. Úloha běží na pozadí. Informace o tom, jak dlouho úloha obvykle trvá, najdete v části Doby zpracování.

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

Parametry

Name
ai_model
Type
string
Povinné
Description
AI model, který generuje obrázek. Ceny se liší podle modelu. Ceny najdete v části Ceny.
Dostupné hodnoty:
- nano-banana: standardní model
- nano-banana-2: schopnější než nano-banana
- nano-banana-2-lite: odlehčená verze modelu nano-banana-2
- nano-banana-2-1: Nano Banana 2.1
- nano-banana-pro: Pro model s vyšší kvalitou. Vyžaduje předplatné Pro nebo vyšší. U nižšího plánu vrátí 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
Povinné
Description
Text, který popisuje obrázek, jenž se má vygenerovat. Podrobnější popis přináší lepší výsledky.
Name
generate_multi_view
Type
boolean
výchozí false
Description
Zda se má vygenerovat obrázek s více pohledy, který zobrazuje objekt z několika úhlů. Pokud je nastaveno na true, nelze odesílat aspect_ratio. Odeslání obou vrátí 400.
Name
pose_mode
Type
string
Description
Pozice postavy, a-pose nebo t-pose. Pokud nechcete žádnou pozici, parametr vynechte.
Způsob fungování pozice závisí na ai_model:
- nano-banana-2, nano-banana-2-lite a nano-banana-2-1: Meshy zachová vámi zvolený model. Obrázek má vždy poměr 3:4 a Meshy ignoruje aspect_ratio.
- nano-banana a nano-banana-pro: Meshy vygeneruje obrázek pomocí nano-banana-pro, takže se ai_model úlohy vrátí jako nano-banana-pro. Vyžaduje to předplatné Pro nebo vyšší. Obrázek má vždy poměr 3:4 a Meshy ignoruje aspect_ratio.
- Modely GPT Image (gpt-image-2, gpt-image-2-5-flare a gpt-image-2-5-sunburst): Meshy zachová vámi zvolený model i vámi zadaný aspect_ratio.
Name
aspect_ratio
Type
string
výchozí 1:1
Description
Tvar obrázku. Hodnoty, které lze odeslat, závisí na ai_model.
Dostupné hodnoty:
- 1:1: čtverec
- 16:9: širokoúhlý na šířku
- 9:16: širokoúhlý na výšku
- 4:3: standardní na šířku
- 3:4: standardní na výšku
- 3:2: na šířku, pouze pro modely GPT Image
- 2:3: na výšku, pouze pro modely GPT Image
Modely řady nano-banana (nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-2-1 a nano-banana-pro) vrátí u hodnot 3:2 a 2:3 chybu 400.
Name
remove_background
Type
boolean
výchozí false
Description
Zda se má odstranit pozadí obrázku. Hodnota true vrátí průhledné PNG v režimu RGBA, takže objekt můžete umístit na libovolné pozadí.

Návratové hodnoty

Pole result v odpovědi obsahuje ID nové úlohy Text na obrázek.

Režimy selhání

Name
400 - Bad Request
Description
Požadavek nelze spustit. Chybová zpráva uvádí, jaký problém byl zjištěn. Například:
- Chybějící parametr: Chybí povinný parametr, například ai_model nebo prompt.
- Neplatný parametr: ai_model nebo aspect_ratio neodpovídá žádné z povolených hodnot.
- Konflikt: aspect_ratio bylo odesláno spolu s generate_multi_view: true.
Opravte požadavek a odešlete jej znovu. Viz Chyby.
Name
401 - Unauthorized
Description
API klíč chybí nebo je neplatný. Zkontrolujte hlavičku Authorization.
Name
402 - Payment Required
Description
Účet nemůže tuto úlohu spustit. Například:
- Bezplatný plán: Vytvoření úlohy vyžaduje placený plán. Upgradujte svůj plán v nastavení předplatného a poté to zkuste znovu.
- Nedostatek kreditů: Účet nemá dostatek kreditů pro tuto úlohu (Insufficient funds), nebo účet dosáhl limitu kreditů.
- Vyžadovaný plán: Požadavek používá nano-banana-pro, nebo pose_mode s nano-banana, u plánu nižšího než Pro (Only Pro and above users can use nano-banana-pro, nebo Only Pro and above users can use A/T pose feature (requires nano-banana-pro)).
Zkontrolujte zůstatek kreditů a svůj plán a poté to zkuste znovu.
Name
429 - Too Many Requests
Description
Překročili jste limit rychlosti. Počkejte a poté to zkuste znovu. Viz Limity rychlosti.

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

Get a Text to Image task

Vrátí úlohu Text na obrázek podle jejího 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=***"
  ]
}

Parametry

Name
id
Type
path
Description
ID úlohy z odpovědi na její vytvoření.

Návratová hodnota

Objekt úlohy Text na obrázek.

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

Smazání úlohy Text na obrázek

Trvale smaže úlohu Text na obrázek, včetně jejích obrázků a dat. Smazání nelze vrátit zpět.

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

Parametry cesty

Name
id
Type
path
Description
ID úlohy, která má být smazána.

Stav úlohy

Smazání úlohy ve stavu PENDING vrátí kredity, které byly použity při jejím vytvoření.

Úlohu ve stavu IN_PROGRESS nelze smazat. Požadavek vrátí 409 Conflict a úloha dál běží. Meshy nevrací kredity za úlohu, která už byla spuštěna, takže smazáním byste přišli jak o kredity, tak o výsledek. Počkejte, až dosáhne stavu SUCCEEDED, FAILED nebo CANCELED, a teprve poté ji smažte.

Smazání úlohy v konečném stavu (SUCCEEDED, FAILED nebo CANCELED) kredity nevrací.

Návratová hodnota

200 OK, pokud byla úloha smazána, nebo 409 Conflict, pokud je úloha ve stavu IN_PROGRESS.

GET/openapi/v1/text-to-image

Seznam úloh Text na obrázek

Vrátí seznam vašich úloh Text na obrázek a Obrázek na obrázek. Pole type u každé úlohy udává, o který z těchto dvou typů se jedná.

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

Parametry

Name
page_num
Type
integer
Description
Číslo stránky, která se má vrátit. Začíná na 1 a to je také výchozí hodnota.
Name
page_size
Type
integer
Description
Počet úloh na stránku, maximálně 100. Výchozí hodnota je 10.
Name
sort_by
Type
string
Description
Pořadí řazení.
Dostupné hodnoty:
- +created_at: od nejstarších
- -created_at: od nejnovějších

Návratová hodnota

Stránkovaný seznam objektů úloh, ve stejném formátu jako objekt úlohy Text na obrázek.

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

Streamování úlohy Text na obrázek

Streamuje aktualizace úlohy Text na obrázek jako 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=***"
  ]
}

Parametry

Name
id
Type
path
Description
ID úlohy z odpovědi na vytvoření.

Návratová hodnota

Proud objektů úlohy Text na obrázek jako Server-Sent Events.

Každá událost obsahuje celý objekt úlohy ve stejné podobě, jakou vrací koncový bod Get. Dokud je úloha ve stavu PENDING nebo IN_PROGRESS, její výsledková pole ještě nemají hodnoty.

Objekt úlohy Text na obrázek

Objekt úlohy Text na obrázek popisuje jedno generování obrázku z textového promptu. Obsahuje stav, progress a URL adresy obrázků, pokud úloha uspěje.

Vlastnosti

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
ID úlohy. Považujte jej za neprůhledný řetězec a nespoléhejte na jeho formát.
Name
type
Type
string
Description
Typ úlohy, vždy text-to-image.
Name
ai_model
Type
string
Description
AI model, který úloha použila.
Možné hodnoty:
- 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
Textový prompt, se kterým jste úlohu vytvořili.
Name
status
Type
string
Description
Stav úlohy, jedna z hodnot PENDING, IN_PROGRESS, SUCCEEDED, FAILED nebo CANCELED.
Name
progress
Type
integer
Description
Jak velká část úlohy je hotová, v procentech. Je 0, dokud úloha nezačne, a 100, když uspěje.
Name
created_at
Type
timestamp
Description
Čas vytvoření úlohy, v milisekundách Unixového času.
Name
started_at
Type
timestamp
Description
Čas zahájení úlohy, v milisekundách Unixového času. Chybí, dokud úloha nezačne.
Name
finished_at
Type
timestamp
Description
Čas dokončení úlohy, v milisekundách Unixového času. Chybí, dokud úloha neskončí.
Name
expires_at
Type
timestamp
Description
Čas, kdy vyprší platnost výsledků úlohy, v milisekundách Unixového času. Chybí, dokud úloha neskončí.
Name
preceding_tasks
Type
integer
Description
Počet úloh před touto úlohou ve frontě. Hodnota má smysl pouze tehdy, když je úloha ve stavu PENDING. Pole se vynechává, pokud je hodnota 0.
Name
image_urls
Type
array
Description
URL adresy ke stažení vygenerovaných obrázků. S generate_multi_view: true obsahuje pole jednu URL adresu na pohled, obvykle tři. Pokud Meshy nedokáže oddělit všechny pohledy, vrátí jich méně a úloha přesto uspěje. Jinak obsahuje jednu URL adresu.
Name
task_error
Type
object
Description
Podrobnosti o chybě, pokud úloha selže. Je null, pokud stav není FAILED. Viz Chyby.
Name
consumed_credits
Type
integer
Description
Počet kreditů, které úloha spotřebovala. Přítomno, pokud je stav PENDING, IN_PROGRESS nebo SUCCEEDED. U úlohy se stavem FAILED je 0, protože Meshy při selhání úlohy kredity vrací.