Text na obrázek API

Text na obrázek API je funkce, která vám umožňuje integrovat schopnosti generování obrázků pomocí AI od Meshy do vaší vlastní aplikace. Generujte vysoce kvalitní obrázky z textových promptů pomocí našich výkonných AI modelů.

Tento koncový bod generuje obrázky. Pokud je cílem objekt, který můžete držet v ruce nebo vytisknout — klíčenka, magnet na lednici, figurka, lampa nebo keycap z fotografie — použijte Creative Lab API (prototypový obrázek → vytvoření 3D modelu). Pokud je cílem 3D model toho, co je na obrázku, použijte Obrázek na 3D.

POST/openapi/v1/text-to-image

Create a Text to Image Task

Tento koncový bod umožňuje vytvořit novou úlohu Text na obrázek. Vlastnosti, které objekt úlohy Text na obrázek obsahuje, naleznete v části Objekt úlohy Text na obrázek.

Úloha běží na pozadí. Informace o tom, jak dlouho to obvykle trvá, naleznete v části Doby zpracování.

Parametry

Name
ai_model
Type
string
Povinné
Description
ID modelu, který se má použít pro generování obrázku.
Dostupné hodnoty:
- nano-banana: Standardní model (3 kredity za obrázek)
- nano-banana-2: Vyvážený model se silnějšími schopnostmi než standardní (6 kreditů za obrázek)
- nano-banana-2-lite: Odlehčená varianta modelu nano-banana-2 (3 kredity za obrázek)
- nano-banana-pro: Pro model s vylepšenou kvalitou (9 kreditů za obrázek)
- gpt-image-2: OpenAI GPT Image 2, obrázkový model s vysokou věrností (9 kreditů za obrázek)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), obrázkový model s vysokou věrností (9 kreditů za obrázek)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), obrázkový model s vysokou věrností (9 kreditů za obrázek)
Name
prompt
Type
string
Povinné
Description
Textový popis obrázku, který chcete vygenerovat. Pro nejlepší výsledky buďte co nejvýstižnější.
Name
generate_multi_view
Type
boolean
výchozí false
Description
Když je nastaveno na true, vygeneruje se obrázek s více pohledy zobrazující subjekt z více úhlů.
Pokud je generate_multi_view nastaveno na true, nelze nastavit parametr aspect_ratio.
Name
pose_mode
Type
string
Description
Zadejte pose_mode pro generování postav. Pokud je vynechán, obrázek se vygeneruje bez jakýchkoli přednastavených póz.
Dostupné hodnoty: a-pose, t-pose
U modelů nano-banana, nano-banana-2, nano-banana-2-lite a nano-banana-pro nastavení pose_mode pevně stanoví výstupní poměr stran na 3:4 a jakýkoli odeslaný aspect_ratio je ignorován. nano-banana-2 a nano-banana-2-lite si zachovají požadovaný model. U nano-banana nebo nano-banana-pro je obrázek s pózou vygenerován pomocí nano-banana-pro (hodnota ai_model úlohy se pak vrátí jako nano-banana-pro), což vyžaduje plán Pro nebo vyšší. Modely GPT Image (gpt-image-2, gpt-image-2-5-flare, gpt-image-2-5-sunburst) si zachovají požadovaný model i aspect_ratio.
Name
aspect_ratio
Type
string
výchozí 1:1
Description
Zadejte poměr stran generovaného obrázku. Povolené hodnoty závisí na vybraném 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
Dostupné hodnoty:
- 1:1: Čtvercový formát
- 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 (podporováno pouze modely GPT Image)
- 2:3: Na výšku (podporováno pouze modely GPT Image)
Name
remove_background
Type
boolean
výchozí false
Description
Když je nastaveno na true, vygenerovaný obrázek se vrátí jako průhledné RGBA PNG s odstraněným pozadím, takže můžete subjekt umístit na libovolné pozadí.

Návratové hodnoty

Vlastnost result v odpovědi obsahuje id úlohy nově vytvořené úlohy Text na obrázek.

Režimy selhání

Name
400 - Bad Request
Description
Požadavek byl nepřijatelný. Časté příčiny:
- Chybějící parametr: Chybí povinný parametr (např. ai_model, prompt).
- Neplatný parametr: ai_model nebo aspect_ratio neodpovídá žádné z povolených hodnot.
- Konflikt: generate_multi_view a aspect_ratio nelze použít současně.
Name
401 - Unauthorized
Description
Autentizace se nezdařila. Zkontrolujte prosím svůj API klíč.
Name
402 - Payment Required
Description
Časté příčiny:
- Nedostatek kreditů: Váš účet nemá dostatek kreditů pro provedení této úlohy (Insufficient funds).
- Vyžadován plán: nano-banana-pro, nebo pose_mode s nano-banana, vyžaduje plán Pro nebo vyšší (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)).
Name
429 - Too Many Requests
Description
Překročili jste svůj limit rychlosti.

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

Získání úlohy Text na obrázek

Tento koncový bod umožňuje získat úlohu Text na obrázek na základě platného id úlohy. Podívejte se na Objekt úlohy Text na obrázek, kde zjistíte, jaké vlastnosti objekt úlohy Text na obrázek obsahuje.

Parametry

Name
id
Type
path
Description
Jedinečný identifikátor úlohy Text na obrázek, kterou chcete získat.

Návratové hodnoty

Odpověď obsahuje objekt úlohy Text na obrázek. Podrobnosti naleznete v části Objekt úlohy Text na obrázek.

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

Smazání úlohy Text na obrázek

Tento koncový bod trvale smaže úlohu Text na obrázek, včetně všech souvisejících obrázků a dat. Tato akce je nevratná.

Parametry cesty

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

Stav úlohy

Úloha, která je stále ve stavu PENDING, je smazána a kredity spotřebované při jejím vytvoření jsou vráceny.

Úlohu, která je již ve stavu IN_PROGRESS, nelze smazat: požadavek je odmítnut s chybou 409 Conflict a úloha pokračuje v běhu. Kredity za úlohu, kterou již worker začal zpracovávat, nejsou vratné, takže její smazání uprostřed běhu by vás stálo jak kredity, tak výsledek. Počkejte, dokud nedosáhne stavu SUCCEEDED, FAILED nebo CANCELED, a poté ji smažte.

Úloha v konečném stavu (SUCCEEDED, FAILED nebo CANCELED) je smazána bez vrácení kreditů.

Návratové hodnoty

Vrací 200 OK v případě úspěchu, nebo 409 Conflict, pokud je úloha ve stavu IN_PROGRESS.

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

List Text to Image Tasks

Tento koncový bod umožňuje načíst seznam úloh Text na obrázek.

Parametry

Name
page_num
Type
integer
Description
Číslo stránky pro stránkování. Začíná a výchozí hodnota je 1.
Name
page_size
Type
integer
Description
Limit velikosti stránky. Výchozí hodnota je 10 položek. Maximální povolená hodnota je 100 položek.
Name
sort_by
Type
string
Description
Pole, podle kterého se má řadit. Dostupné hodnoty:
- +created_at: Řadit podle času vytvoření vzestupně.
- -created_at: Řadit podle času vytvoření sestupně.

Návratové hodnoty

Vrací stránkovaný seznam objektů úlohy Text na obrázek.

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

Streamování úlohy Text na obrázek

Tento koncový bod streamuje aktualizace v reálném čase pro úlohu Text na obrázek pomocí Server-Sent Events (SSE).

Parametry

Name
id
Type
path
Description
Jedinečný identifikátor úlohy Text na obrázek, kterou chcete streamovat.

Návratová hodnota

Vrací stream Objektů úlohy Text na obrázek formou Server-Sent Events.

U úloh ve stavu PENDING nebo IN_PROGRESS bude streamovaná odpověď obsahovat pouze nezbytná pole progress a 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=***"
  ]
}

Objekt úkolu Text na obrázek

Objekt úkolu Text na obrázek je pracovní jednotka, kterou Meshy sleduje za účelem vygenerování obrázku ze vstupního textového promptu. Objekt má následující vlastnosti:

Vlastnosti

Name
id
Type
string
Description
Jedinečný identifikátor úkolu. I když jako implementační detail používáme pro id úkolů k-sortovatelné UUID, neměli byste dělat žádné předpoklady o formátu id.
Name
type
Type
string
Description
Typ úkolu generování obrázku. U úkolů Text na obrázek bude toto vždy text-to-image.
Name
ai_model
Type
string
Description
AI model použitý pro tento úkol. Možné hodnoty jsou nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro, gpt-image-2, gpt-image-2-5-flare nebo gpt-image-2-5-sunburst.
Name
prompt
Type
string
Description
Textový prompt, který byl použit k vygenerování obrázku.
Name
status
Type
string
Description
Stav úkolu. Možné hodnoty jsou jedna z PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Průběh úkolu. Pokud úkol ještě nebyl spuštěn, tato vlastnost bude 0. Jakmile úkol úspěšně skončí, bude mít hodnotu 100.
Name
created_at
Type
timestamp
Description
Časové razítko okamžiku vytvoření úkolu, v milisekundách.
Časové razítko představuje počet milisekund, které uplynuly od 1. ledna 1970 UTC, podle normy RFC 3339. Například pátek 1. září 2023 12:00:00 PM GMT je reprezentován jako 1693569600000. To platí pro všechna časová razítka v Meshy API.
Name
started_at
Type
timestamp
Description
Časové razítko okamžiku spuštění úkolu, v milisekundách. Pokud úkol ještě nebyl spuštěn, tato vlastnost bude 0.
Name
finished_at
Type
timestamp
Description
Časové razítko okamžiku dokončení úkolu, v milisekundách. Pokud úkol ještě není dokončen, tato vlastnost bude 0.
Name
expires_at
Type
timestamp
Description
Časové razítko okamžiku, kdy vyprší platnost výsledku úkolu, v milisekundách.
Name
preceding_tasks
Type
integer
Description
Počet předcházejících úkolů.
Hodnota tohoto pole má smysl pouze v případě, že stav úkolu je PENDING.
Name
image_urls
Type
array
Description
Pole stažitelných URL adres vygenerovaných obrázků. Když je povoleno generate_multi_view, toto pole obsahuje tři URL adresy obrázků reprezentující různé úhly pohledu. Jinak obsahuje jedinou URL adresu obrázku.
Name
task_error
Type
object
Description
Podrobnosti o chybě u neúspěšných úkolů. Úplný referenční popis objektu task_error najdete v části Chyby.
Name
consumed_credits
Type
integer
Description
Počet kreditů spotřebovaných tímto úkolem. Je přítomno, pokud je stav úkolu PENDING, IN_PROGRESS nebo SUCCEEDED. U úkolů se stavem FAILED vrací 0 (při selhání jsou kredity vráceny).

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
}