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é jsou součástí objektu úlohy Text na obrázek, naleznete v The Text to Image Task Object.

Úloha běží na pozadí. Jak dlouho to obvykle trvá, se dozvíte v části Processing Times.

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 se zvýšenou kvalitou (9 kreditů za obrázek)
- gpt-image-2: OpenAI GPT Image 2, vysoce věrný model obrázků (9 kreditů za obrázek)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), vysoce věrný model obrázků (9 kreditů za obrázek)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), vysoce věrný model obrázků (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 nejpopisnější.
Name
generate_multi_view
Type
boolean
výchozí false
Description
Pokud je nastaveno na true, vygeneruje se obrázek s více pohledy, který zobrazuje subjekt z více úhlů.
Pokud je generate_multi_view nastaveno na true, nelze nastavit parametr aspect_ratio.
Name
pose_mode
Type
string
Description
Určete mode pozy pro generování postavy. Pokud není zadáno, obrázek se vygeneruje bez jakýchkoli přednastavených póz.
Dostupné hodnoty: a-pose, t-pose
Name
aspect_ratio
Type
string
výchozí 1:1
Description
Určete poměr stran generovaného obrázku. Povolené hodnoty závisí na zvolené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
Pokud je nastaveno na true, vygenerovaný obrázek je vrácen jako průhledný RGBA PNG s odstraněným pozadím, takže můžete subjekt vložit na jakékoli 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ý. Běžné 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 selhala. Zkontrolujte prosím svůj API klíč.
Name
402 - Payment Required
Description
Nedostatek kreditů k provedení této úlohy.
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í úkolu Text na obrázek

Tento koncový bod umožňuje získat úkol Text na obrázek na základě platného id úkolu. Podrobnosti o vlastnostech, které jsou součástí objektu úkolu Text na obrázek, naleznete v části Objekt úkolu Text na obrázek.

Parametry

Name
id
Type
path
Description
Jedinečný identifikátor úkolu Text na obrázek, který má být získán.

Návratová hodnota

Odpověď obsahuje objekt úkolu Text na obrázek. Podrobnosti naleznete v části Objekt úkolu 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, kterou chcete smazat.

Stav úlohy

Úloha, která je stále ve stavu PENDING, je smazána a kredity spotřebované při 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 nadále běží. Kredity za úlohu, kterou už worker začal zpracovávat, nejsou vratné, takže smazání během běhu by vás stálo jak kredity, tak výsledek. Počkejte, až dosáhne stavu SUCCEEDED, FAILED nebo CANCELED, a poté ji smažte.

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

Návratové hodnoty

Vrací 200 OK při ú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

Seznam úloh Text na obrázek

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: Seřadit podle času vytvoření vzestupně.
- -created_at: Seřadit podle času vytvoření sestupně.

Vrací

Vrací stránkovaný seznam objektů úloh 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, pro kterou se má spustit streamování.

Návratová hodnota

Vrací proud objektů úlohy Text na obrázek jako Server-Sent Events.

U úloh se stavem PENDING nebo IN_PROGRESS bude proud odpovědí 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=***"
  ]
}

The Text to Image Task Object

Objekt Text to Image Task je pracovní jednotka, kterou Meshy sleduje za účelem generová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 úlohy. I když jako implementační detail používáme pro id úloh k-sortable UUID, neměli byste si o formátu id dělat žádné předpoklady.
Name
type
Type
string
Description
Typ úlohy generování obrázku. U úloh Text to Image bude vždy text-to-image.
Name
ai_model
Type
string
Description
Model AI použitý pro tuto úlohu. 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 ke generování obrázku.
Name
status
Type
string
Description
Stav úlohy. Možné hodnoty jsou jedna z PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Postup úlohy. Pokud úloha ještě nebyla spuštěna, tato vlastnost bude 0. Jakmile úloha uspěje, stane se 100.
Name
created_at
Type
timestamp
Description
Časové razítko okamžiku, kdy byla úloha vytvořena, 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 GMT je reprezentován jako 1693569600000. Toto platí pro všechna časová razítka v Meshy API.
Name
started_at
Type
timestamp
Description
Časové razítko okamžiku, kdy byla úloha spuštěna, v milisekundách. Pokud úloha ještě nebyla spuštěna, tato vlastnost bude 0.
Name
finished_at
Type
timestamp
Description
Časové razítko okamžiku, kdy byla úloha dokončena, v milisekundách. Pokud úloha ještě nebyla dokončena, tato vlastnost bude 0.
Name
expires_at
Type
timestamp
Description
Časové razítko okamžiku, kdy vyprší platnost výsledku úlohy, v milisekundách.
Name
preceding_tasks
Type
integer
Description
Počet předcházejících úloh.
Hodnota tohoto pole má smysl pouze tehdy, pokud je stav úlohy 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ů představující různé pohledy. V opačném případě obsahuje jedinou URL adresu obrázku.
Name
task_error
Type
object
Description
Podrobnosti o chybě u neúspěšných úloh. Úplný popis objektu task_error najdete v Chyby.
Name
consumed_credits
Type
integer
Description
Počet kreditů spotřebovaných touto úlohou. Přítomno, pokud je stav úlohy PENDING, IN_PROGRESS nebo SUCCEEDED. U úloh 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
}