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 podnětů pomocí našich výkonných AI modelů.

POST/openapi/v1/text-to-image

Vytvoření úlohy Text na obrázek

Tento koncový bod vám umožňuje vytvořit novou úlohu Text na obrázek. Podívejte se na Objekt úlohy Text na obrázek, abyste zjistili, které vlastnosti jsou zahrnuty v objektu úlohy Text na obrázek.

Parametry

  • Name
    ai_model
    Type
    string
    Povinné
    Description

    ID modelu, který se použije 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 s vylepšenou kvalitou (9 kreditů za obrázek)
    • gpt-image-2: OpenAI GPT Image 2, model s vysokou věrností obrazu (9 kreditů za obrázek)
  • Name
    prompt
    Type
    string
    Povinné
    Description

    Textový popis obrázku, který chcete vygenerovat. Buďte popisní pro nejlepší výsledky.

  • Name
    generate_multi_view
    Type
    boolean
    výchozí false
    Description

    Když je nastaveno na true, generuje obrázek s více pohledy, který zobrazuje objekt z více úhlů.

    Když je generate_multi_view nastaveno na true, parametr aspect_ratio nelze nastavit.

  • Name
    pose_mode
    Type
    string
    Description

    Určete pose mode pro generování postavy. Pokud není uvedeno, obrázek je generován bez jakýchkoli přednastavených pozic.

    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 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: 1:1, 16:9, 9:16, 3:2, 2:3

    Dostupné hodnoty:

    • 1:1: Čtvercový formát
    • 16:9: Širokoúhlý krajina
    • 9:16: Širokoúhlý portrét
    • 4:3: Standardní krajina (není podporováno gpt-image-2)
    • 3:4: Standardní portrét (není podporováno gpt-image-2)
    • 3:2: Krajina (pouze podporováno gpt-image-2)
    • 2:3: Portrét (pouze podporováno gpt-image-2)
  • Name
    remove_background
    Type
    boolean
    výchozí false
    Description

    Když je nastaveno na true, generovaný obrázek je vrácen jako průhledný RGBA PNG s odstraněným pozadím, takže můžete objekt složit na jakékoli pozadí.

Návratové hodnoty

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

Chybové stavy

  • Name
    400 - Bad Request
    Description

    Požadavek byl nepřijatelný. Běžné příčiny:

    • Chybějící parametr: Chybí požadovaný parametr (např. ai_model, prompt).
    • Neplatný parametr: ai_model nebo aspect_ratio není jednou 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

    Nedostatečné kredity pro provedení této úlohy.

  • Name
    429 - Too Many Requests
    Description

    Překročili jste svůj limit rychlosti.

Požadavek

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

Odpověď

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
GET/openapi/v1/text-to-image/:id

Načíst úkol Text na obrázek

Tento koncový bod vám umožňuje načíst úkol Text na obrázek pomocí platného id úkolu. Podívejte se na Objekt úkolu Text na obrázek, abyste viděli, které vlastnosti jsou zahrnuty v objektu úkolu Text na obrázek.

Parametry

  • Name
    id
    Type
    path
    Description

    Unikátní identifikátor pro úkol Text na obrázek, který chcete načíst.

Návratové hodnoty

Odpověď obsahuje objekt úkolu Text na obrázek. Podrobnosti naleznete v sekci Objekt úkolu Text na obrázek.

Požadavek

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

Odpověď

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

Vrací

Vrací 200 OK při úspěchu.

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

// Returns 200 Ok on success.
GET/openapi/v1/text-to-image

Seznam úkolů Text na obrázek

Tento koncový bod vám umožňuje získat seznam úkolů 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 50 položek.

  • Name
    sort_by
    Type
    string
    Description

    Pole pro řazení. Dostupné hodnoty:

    • +created_at: Řadit podle času vytvoření vzestupně.
    • -created_at: Řadit podle času vytvoření sestupně.

Vrací

Vrací stránkovaný seznam Objektů úkolu Text na obrázek.

Požadavek

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

Odpověď

[
  {
    "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

    Unikátní identifikátor pro úlohu Text na obrázek ke streamování.

Návratové hodnoty

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

Pro úlohy ve stavu PENDING nebo IN_PROGRESS bude stream odpovědi obsahovat pouze potřebná 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 pro generování obrázku z vstupu textového promptu. Objekt má následující vlastnosti:

Vlastnosti

  • Name
    id
    Type
    string
    Description

    Unikátní identifikátor úlohy. I když používáme k-tříditelné UUID pro id úloh jako implementační detail, neměli byste dělat žádné předpoklady o formátu id.

  • Name
    type
    Type
    string
    Description

    Typ úlohy generování obrázku. Pro úlohy Text na obrázek to bude 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 nebo gpt-image-2.

  • Name
    prompt
    Type
    string
    Description

    Textový prompt, který byl použit pro 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ě nezačala, tato vlastnost bude 0. Jakmile úloha uspěje, stane se 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Časové razítko, kdy byla úloha vytvořena, 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 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, kdy byla úloha spuštěna, v milisekundách. Pokud úloha ještě nezačala, tato vlastnost bude 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Časové razítko, kdy byla úloha dokončena, v milisekundách. Pokud úloha ještě není dokončena, tato vlastnost bude 0.

  • Name
    expires_at
    Type
    timestamp
    Description

    Časové razítko, kdy výsledek úlohy vyprší, v milisekundách.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Počet předcházejících úloh.

    Hodnota tohoto pole má smysl pouze pokud je stav úlohy PENDING.

  • Name
    image_urls
    Type
    array
    Description

    Pole stahovatelných URL k vygenerovaným obrázkům. Když je povoleno generate_multi_view, toto pole obsahuje tři URL obrázků představující různé úhly pohledu. Jinak obsahuje jednu URL obrázku.

  • Name
    task_error
    Type
    object
    Description

    Podrobnosti o chybě pro neúspěšné úlohy. Viz Chyby pro úplný odkaz na objekt task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Počet kreditů spotřebovaných touto úlohou. Přítomno, když je stav úlohy PENDING, IN_PROGRESS nebo SUCCEEDED. Vrací 0 pro úlohy FAILED (kredity jsou vráceny při selhání).

Příklad objektu úlohy Text na obrázek

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