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ů.

POST/openapi/v1/text-to-image

Vytvoření úlohy Text na obrázek

Tento koncový bod umožňuje vytvořit novou úlohu Text na obrázek. Podívejte se na Objekt úlohy Text na obrázek, kde najdete přehled vlastností, které objekt úlohy Text na obrázek obsahuje.

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-pro: Pro model se zvýš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íce popisní.

  • Name
    generate_multi_view
    Type
    boolean
    výchozí false
    Description

    Pokud je nastaveno na true, vygeneruje obrázek zobrazující předmět z více úhlů (Více pohledů).

    Pokud je generate_multi_view nastaveno na true, nelze nastavit parametr aspect_ratio.

  • Name
    pose_mode
    Type
    string
    Description

    Určuje pose_mode 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čuje poměr stran vygenerovaného obrázku. Povolené hodnoty závisí na vybraném ai_model:

    • nano-banana, nano-banana-2, 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 se vrátí jako transparentní PNG RGBA s odstraněným pozadím, takže můžete daný objekt umístit na jakékoli jiné pozadí.

Návratová hodnota

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

Způsoby 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

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

Objekt úlohy Text na obrázek

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

Vlastnosti

  • Name
    id
    Type
    string
    Description

    Jedinečný identifikátor úlohy. Ačkoli jako implementační detail používáme pro id úloh k-sortable UUID, neměli byste dělat žádné předpoklady o formátu id.

  • Name
    type
    Type
    string
    Description

    Typ úlohy generování obrázku. U úloh Text na obrázek bude tato hodnota vždy text-to-image.

  • Name
    ai_model
    Type
    string
    Description

    AI model použitý pro tuto úlohu. Možné hodnoty jsou nano-banana, nano-banana-2, 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

    Průběh úlohy (progress). Pokud úloha ještě nebyla zahájena, bude tato vlastnost 0. Jakmile úloha uspěje, stane se 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Časové razítko okamžiku vytvoření úlohy, v milisekundách.

    Časové razítko představuje počet milisekund uplynulých od 1. ledna 1970 UTC, podle standardu 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 zahájení úlohy, v milisekundách. Pokud úloha ještě nebyla zahájena, bude tato vlastnost 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Časové razítko okamžiku dokončení úlohy, v milisekundách. Pokud úloha ještě není dokončena, bude tato vlastnost 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 v případě, že stav úlohy je PENDING.

  • Name
    image_urls
    Type
    array
    Description

    Pole stažitelných URL adres vygenerovaných obrázků. Když je povoleno generate_multi_view, obsahuje toto pole tři URL adresy obrázků reprezentující různé úhly pohledu. V opačném případě obsahuje jednu URL adresu obrázku.

  • Name
    task_error
    Type
    object
    Description

    Podrobnosti o chybě pro neúspěšné úlohy. Úplný přehled objektu task_error naleznete v části Chyby.

  • Name
    consumed_credits
    Type
    integer
    Description

    Počet kreditů spotřebovaných touto úlohou. Je přítomen, když je stav úlohy PENDING, IN_PROGRESS nebo SUCCEEDED. U úloh se stavem FAILED vrací 0 (kredity jsou v případě neúspěchu 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
}