Obrázek na obrázek API

Obrázek na obrázek API je funkce, která vám umožňuje integrovat schopnosti AI editace obrázků od Meshy do vaší vlastní aplikace. Transformujte a upravujte existující obrázky pomocí referenčních obrázků a textových promptů s využitím našich výkonných AI modelů.

POST/openapi/v1/image-to-image

Create an Image to Image Task

Tento koncový bod umožňuje vytvořit nový úkol Obrázek na obrázek. Podívejte se na Objekt úkolu Obrázek na obrázek, kde zjistíte, jaké vlastnosti obsahuje objekt úkolu Obrázek na obrázek.

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, model pro úpravu obrázků s vysokou věrností (12 kreditů za obrázek)
    • gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), model pro úpravu obrázků s vysokou věrností (12 kreditů za obrázek)
    • gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), model pro úpravu obrázků s vysokou věrností (12 kreditů za obrázek)
  • Name
    prompt
    Type
    string
    Povinné
    Description

    Textový popis transformace nebo úpravy, kterou chcete použít na referenční obrázky.

Vyžadován je pouze jeden z parametrů input_task_id nebo reference_image_urls. Pokud jsou zadány oba, input_task_id má prioritu.

  • Name
    input_task_id
    Type
    string
    Povinné
    Description

    ID dokončeného úkolu generování obrázku, jehož výstupní obrázky se mají použít jako referenční obrázky. Tento úkol musí být jedním z následujících typů úkolů: Text na obrázek nebo Obrázek na obrázek, včetně jejich variant s více pohledy. Kromě toho musí být spuštěn prostřednictvím API a mít stav SUCCEEDED.

    Používají se všechny výstupní obrázky zdrojového úkolu. Úkol s jedním obrázkem přispívá 1 referenčním obrázkem; úkol s více pohledy přispívá jedním obrázkem za každý vygenerovaný pohled, takže jedno ID úkolu může zaplnit několik z 5 referenčních míst.

    Zdrojový úkol musí být stále v rámci období uchování assetů — jakmile vyprší, jeho ID vrátí 404.

  • Name
    reference_image_urls
    Type
    array
    Povinné
    Description

    Pole 1 až 5 referenčních obrázků, které se mají použít pro úkol úpravy obrázku. Aktuálně podporujeme formáty .jpg, .jpeg a .png.

    Existují dva způsoby, jak zadat každý obrázek:

    • Veřejně přístupná URL adresa: URL adresa, která je přístupná z veřejného internetu.
    • Data URI: Base64 kódovaná Data URI adresa obrázku. Příklad Data URI: data:image/jpeg;base64,<vaše base64 kódovaná data obrázku>.
  • Name
    generate_multi_view
    Type
    boolean
    výchozí false
    Description

    Když je nastaveno na true, vygeneruje obrázek s více pohledy zobrazující subjekt z různých úhlů.

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

  • Name
    aspect_ratio
    Type
    string
    výchozí 1:1
    Description

    Určete poměr stran výstupního obrázku. Povolené hodnoty závisí na zvolené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

    Když je nastaveno na true, výstupní obrázek je vrácen jako průhledné RGBA PNG s odstraněným pozadím, takže můžete subjekt sloučit s libovolným pozadím.

Návratové hodnoty

Vlastnost result v odpovědi obsahuje id úkolu nově vytvořeného úkolu Obrázek 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), nebo nebyl zadán ani reference_image_urls, ani input_task_id.
    • Neplatný vstupní úkol: input_task_id musí odkazovat na úkol Text na obrázek nebo Obrázek na obrázek se stavem SUCCEEDED (včetně varianty s více pohledy), který stále má výstupní obrázky. Úkol jiného typu, úkol, který nebyl úspěšný, nebo úkol, jehož obrázky již všechny expirovaly, je odmítnut.
    • Neplatný formát obrázku: Jeden nebo více referenčních obrázků nemá podporovaný formát.
    • Nedostupná URL adresa: Jednu nebo více reference_image_urls se nepodařilo stáhnout.
    • Neplatný parametr: aspect_ratio není jednou z povolených hodnot pro zvolený ai_model.
    • 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í tohoto úkolu.

  • Name
    404 - Not Found
    Description

    input_task_id neodkazuje na úkol vlastněný vaším účtem. Úkol, který neexistuje, a úkol patřící jinému účtu vracejí stejnou odpověď.

  • Name
    429 - Too Many Requests
    Description

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

Request

POST
/openapi/v1/image-to-image
# Transform a reference image with a text prompt
curl https://api.meshy.ai/openapi/v1/image-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "reference_image_urls": [
      "<your publicly accessible image url or base64-encoded data URI>"
    ]
  }'


 ## Using Data URI example
curl https://api.meshy.ai/openapi/v1/image-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "reference_image_urls": [
      "data:image/png;base64,${YOUR_BASE64_ENCODED_IMAGE_DATA}"
    ]
  }'


 ## Chaining from a previous task, instead of passing image URLs
curl https://api.meshy.ai/openapi/v1/image-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "input_task_id": "<your Text to Image or Image to Image task id>"
  }'

Response

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

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

Tento koncový bod umožňuje získat úlohu Obrázek na obrázek na základě platného id úlohy. Podívejte se na The Image to Image Task Object, kde najdete vlastnosti obsažené v objektu úlohy Obrázek na obrázek.

Parametry

  • Name
    id
    Type
    path
    Description

    Jedinečný identifikátor úlohy Obrázek na obrázek, kterou chcete získat.

Návratová hodnota

Odpověď obsahuje objekt úlohy Obrázek na obrázek. Podrobnosti najdete v sekci The Image to Image Task Object.

Request

GET
/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578
curl https://api.meshy.ai/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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/image-to-image/:id

Smazání úlohy Obrázek na obrázek

Tento koncový bod trvale smaže úlohu Obrázek 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 Obrázek 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 zamí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í uprostřed zpracování by vás stálo jak kredity, tak výsledek. Počkejte, až úloha 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

Při úspěchu vrací 200 OK, nebo 409 Conflict, pokud je úloha ve stavu IN_PROGRESS.

Request

DELETE
/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/image-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/image-to-image

Vypsat úlohy Obrázek na obrázek

Tento koncový bod umožňuje načíst seznam úloh Obrázek 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: Řazení podle času vytvoření vzestupně.
    • -created_at: Řazení podle času vytvoření sestupně.

Návratová hodnota

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

Request

GET
/openapi/v1/image-to-image
curl https://api.meshy.ai/openapi/v1/image-to-image?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "image-to-image",
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "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/image-to-image/:id/stream

Streamování úlohy Obrázek na obrázek

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

Parametry

  • Name
    id
    Type
    path
    Description

    Jedinečný identifikátor úlohy Obrázek na obrázek, kterou chcete streamovat.

Návratová hodnota

Vrací proud objektů úlohy Obrázek na obrázek ve formě Server-Sent Events.

U úloh se stavem PENDING nebo IN_PROGRESS bude proud odpovědi obsahovat pouze nezbytná pole progress a status.

Request

GET
/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.ai/openapi/v1/image-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": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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 Obrázek na obrázek

Objekt úlohy Obrázek na obrázek je pracovní jednotka, kterou Meshy sleduje za účelem generování obrázku z referenčních obrázků a vstupu textového promptu. Objekt má následující vlastnosti:

Vlastnosti

  • Name
    id
    Type
    string
    Description

    Jedinečný identifikátor úlohy. Přestože 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 Obrázek na obrázek bude tato hodnota vždy image-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 k řízení transformace 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. Pokud úloha ještě nebyla zahájena, tato vlastnost bude 0. Jakmile úloha uspěje, hodnota se stane 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, tato vlastnost bude 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, 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 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ů reprezentující různé úhly pohledu. Jinak obsahuje jednu URL adresu obrázku.

  • Name
    task_error
    Type
    object
    Description

    Podrobnosti o chybě u neúspěšných úloh. Úplnou referenci objektu task_error naleznete v části Chyby.

  • 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. Pro úlohy se stavem FAILED vrací 0 (v případě selhání jsou kredity vráceny).

Example Image to Image Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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
}