Obrázek na obrázek API

Obrázek na obrázek API je funkce, která vám umožňuje integrovat Meshy AI schopnosti úpravy obrázků do vlastní aplikace. Transformujte a upravujte existující obrázky pomocí referenčních obrázků a textových promptů s našimi výkonnými AI modely.

Tento koncový bod vytváří obrázky. Pokud je cílem předmět, který lze držet nebo vytisknout — klíčenka, magnet na lednici, figurka, lampa nebo keycap z fotografie — použijte Creative Lab API (obrázek prototypu → 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/image-to-image

Vytvoření úlohy Obrázek na obrázek

Tento koncový bod umožňuje vytvořit novou úlohu Obrázek na obrázek. Vlastnosti obsažené v objektu úlohy Obrázek na obrázek naleznete v části Objekt úlohy Obrázek 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ázků.
Dostupné hodnoty:
- nano-banana: Standardní model (3 kredity na obrázek)
- nano-banana-2: Vyvážený model se silnějšími schopnostmi než standardní (6 kreditů na obrázek)
- nano-banana-2-lite: Odlehčená varianta modelu nano-banana-2 (3 kredity na obrázek)
- nano-banana-pro: Pro model se zvýšenou kvalitou (9 kreditů na obrázek)
- gpt-image-2: OpenAI GPT Image 2, vysoce věrný model pro úpravu obrázků (12 kreditů na obrázek)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), vysoce věrný model pro úpravu obrázků (12 kreditů na obrázek)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), vysoce věrný model pro úpravu obrázků (12 kreditů na obrázek)
Name
prompt
Type
string
Povinné
Description
Textový popis transformace nebo úpravy, kterou chcete použít na referenční obrázky.

Je vyžadován pouze jeden z parametrů input_task_id nebo reference_image_urls. Pokud jsou zadány oba, má přednost input_task_id.

Name
input_task_id
Type
string
Povinné
Description
ID dokončené úlohy generování obrázku, jejíž výstupní obrázky mají být použity jako referenční obrázky. Tato úloha musí být jednou z následujících: 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ěna přes API a musí mít stav SUCCEEDED.
Použijí se všechny výstupní obrázky zdrojové úlohy. Úloha s jedním obrázkem přispívá 1 referenčním obrázkem; úloha s více pohledy přispívá jedním obrázkem na každý vygenerovaný pohled, takže jedno ID úlohy může zaplnit několik z 5 referenčních slotů.
Zdrojová úloha musí být stále v rámci doby uchování assetů – jakmile vyprší, její 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 úlohu úpravy obrázku. Aktuálně podporujeme formáty .jpg, .jpeg, .png a .webp.
Maximální velikost souboru: 20 MB na obrázek.
Existují dva způsoby, jak poskytnout každý obrázek:
- Veřejně přístupná URL: URL, která je přístupná z veřejného internetu.
- Data URI: Obrázek zakódovaný do base64 jako data URI. Příklad data URI: data:image/jpeg;base64,<vaše base64 zakódovaná data obrázku>.

Name
generate_multi_view
Type
boolean
výchozí false
Description
Pokud je nastaveno na true, vygeneruje se obrázek s více pohledy zobrazující objekt z několika úhlů.
Pokud je generate_multi_view nastaveno na true, nelze nastavit parametr aspect_ratio.
Name
aspect_ratio
Type
string
výchozí 1:1
Description
Určuje poměr stran výstupní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
Pokud je nastaveno na true, výstupní obrázek je vrácen jako transparentní RGBA PNG s odstraněným pozadím, takže můžete objekt vložit do jakéhokoli pozadí.

Návratová hodnota

Vlastnost result odpovědi obsahuje id úlohy nově vytvořené úlohy Obrázek 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), nebo nebyl zadán ani reference_image_urls, ani input_task_id.
- Neplatná vstupní úloha: input_task_id musí odkazovat na úlohu Text na obrázek nebo Obrázek na obrázek (včetně variant s více pohledy) se stavem SUCCEEDED, která stále má výstupní obrázky. Úloha jiného typu, úloha, která neuspěla, nebo úloha, jejíž obrázky všechny vypršely, je odmítnuta.
- Neplatný formát obrázku: Jeden nebo více referenčních obrázků nemá podporovaný formát.
- Nedostupná URL: Jednu nebo více reference_image_urls se nepodařilo stáhnout.
- Obrázek je příliš velký: Jeden nebo více obrázků v reference_image_urls přesahuje 20 MB.
- Neplatný parametr: aspect_ratio není jednou z povolených hodnot pro vybraný 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í této úlohy.
Name
404 - Not Found
Description
input_task_id neodkazuje na úlohu patřící vašemu účtu. Úloha, která neexistuje, a úloha patřící jinému účtu vrací 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 Image to Image

Objekt úlohy Image to Image je pracovní jednotka, kterou Meshy sleduje za účelem vygenerování obrázku z referenčních obrázků a vstupu typu textový prompt. 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-seřaditelné 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 Image to Image bude 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-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 ří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
Postup (progress) úlohy. 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 vytvoření úlohy, v milisekundách.
Časové razítko představuje počet milisekund, které uplynuly 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 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 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, 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ů. Pokud je povoleno generate_multi_view, obsahuje toto pole tři URL adresy obrázků představují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 úloh. Úplný popis objektu task_error najdete v části 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 (kredity jsou v případě selhání 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
}