Obrázek na obrázek API

Upravujte a transformujte obrázky ve své vlastní aplikaci. Odešlete referenční obrázky a textový prompt a AI modely Meshy z nich vygenerují nový obrázek.

Obrázek na obrázek vytváří obrázky. Chcete-li vytvořit 3D model toho, co je na obrázku, použijte Obrázek na 3D. Chcete-li z fotografie vytvořit objekt, který lze držet v ruce nebo vytisknout, použijte Creative Lab APIs. Ty nejprve vytvoří prototypový obrázek a poté z něj sestaví 3D model, například klíčenku, magnet na lednici, figurku, lampu nebo keycap.

POST/openapi/v1/image-to-image

Create an Image to Image task

Vytvoří úkol Obrázek na obrázek. Úkol běží na pozadí. Jak dlouho úkol obvykle trvá, se dozvíte v části Doby zpracování.

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

Parametry

Name
ai_model
Type
string
Povinné
Description
AI model, který generuje obrázek. Ceny se liší podle modelu. Viz Ceny.
Dostupné hodnoty:
- nano-banana: standardní model
- nano-banana-2: schopnější než nano-banana
- nano-banana-2-lite: odlehčená verze modelu nano-banana-2
- nano-banana-2-1: Nano Banana 2.1
- nano-banana-pro: Pro model s vyšší kvalitou. Vyžaduje plán Pro nebo vyšší. Na nižším plánu vrací 402.
- gpt-image-2: OpenAI GPT Image 2
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst)
Name
prompt
Type
string
Povinné
Description
Text, který popisuje úpravu nebo transformaci, jež se má na referenční obrázky použít.

Name
input_task_id
Type
string
Povinné
Description
Povinné, pokud neodešlete reference_image_urls. ID úkolu Text na obrázek nebo Obrázek na obrázek, jehož obrázky se použijí jako reference, včetně úkolů s více pohledy. Úkol musí být vytvořen vámi pomocí API a musí mít stav SUCCEEDED.
Meshy použije každý obrázek, který úkol vytvořil. Úkol s jedním obrázkem poskytne jeden referenční obrázek, úkol s více pohledy poskytne jeden obrázek na každý pohled. Jedno ID úkolu tak může zaplnit několik z pěti referenčních slotů.
Úkol musí stále spadat do doby uchování assetů. Po jejím vypršení vrátí jeho ID 404.

Name
reference_image_urls
Type
array
Povinné
Description
Povinné, pokud neodešlete input_task_id. Jeden až pět referenčních obrázků k úpravě, každý jako veřejná URL adresa nebo Data URI, například data:image/jpeg;base64,<vaše base64 zakódovaná obrazová data>. Prázdné pole nebo více než pět obrázků vrátí 400. Pokud odešlete obojí, Meshy použije input_task_id.
Každý obrázek musí být soubor .jpg, .jpeg, .png nebo .webp o velikosti nejvýše 20 MB a s každou stranou dlouhou alespoň 32 pixelů.

Name
generate_multi_view
Type
boolean
výchozí false
Description
Zda vygenerovat obrázek s více pohledy, který zobrazuje subjekt z několika úhlů. Když je true, nemůžete odeslat aspect_ratio. Odeslání obojího vrátí 400.
Name
aspect_ratio
Type
string
výchozí 1:1
Description
Poměr stran výstupního obrázku. Hodnoty, které můžete odeslat, závisí na ai_model.
Dostupné hodnoty:
- 1:1: čtverec
- 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, pouze modely GPT Image
- 2:3: na výšku, pouze modely GPT Image
Modely GPT Image jsou gpt-image-2, gpt-image-2-5-flare a gpt-image-2-5-sunburst. U modelu nano-banana vrací 3:2 a 2:3 chybu 400.
Name
remove_background
Type
boolean
výchozí false
Description
Zda odstranit pozadí. Když je true, Meshy vrátí výstupní obrázek jako průhledné RGBA PNG, takže subjekt můžete umístit na jakékoli pozadí.

Návratové hodnoty

Pole result v odpovědi obsahuje ID nového úkolu Obrázek na obrázek.

Způsoby selhání

Name
400 - Bad Request
Description
Požadavek nelze spustit. Chybová zpráva uvádí, jaký problém byl zjištěn. Například:
- Chybějící parametr: Chybí povinný parametr, například ai_model nebo prompt, nebo nebylo odesláno ani reference_image_urls, ani input_task_id.
- Neplatný vstupní úkol: input_task_id neodkazuje na použitelný úkol. Musí jít o úkol Text na obrázek nebo Obrázek na obrázek ve stavu SUCCEEDED, včetně úkolů s více pohledy, který stále má výstupní obrázky. Meshy odmítne úkol jiného typu, úkol, který neuspěl, a úkol, jehož všechny obrázky vypršely.
- Neplatný formát obrázku: Jeden nebo více referenčních obrázků není v podporovaném formátu.
- Nedostupná URL adresa: Meshy nemůže stáhnout jeden nebo více obrázků reference_image_urls.
- Obrázek je příliš velký: Jeden nebo více obrázků reference_image_urls přesahuje 20 MB.
- Obrázek je příliš malý: Jeden nebo více obrázků reference_image_urls má stranu kratší než 32 pixelů.
- Neplatný parametr: aspect_ratio neodpovídá žádné z hodnot, které zvolený ai_model podporuje.
- Konflikt: Požadavek odesílá aspect_ratio společně s generate_multi_view: true.
Opravte požadavek a odešlete jej znovu. Viz Chyby.
Name
401 - Unauthorized
Description
API klíč chybí nebo je neplatný. Zkontrolujte hlavičku Authorization.
Name
402 - Payment Required
Description
Účet nemůže tento úkol spustit. Například:
- Bezplatný plán: Vytvoření úkolu vyžaduje placený plán. Upgradujte svůj plán v nastavení předplatného a zkuste to znovu.
- Nedostatek kreditů: Účet nemá dostatek kreditů pro tento úkol, nebo účet dosáhl limitu kreditů.
- Vyžadován plán: Požadavek používá nano-banana-pro na plánu nižším než Pro.
Zkontrolujte zůstatek kreditů a svůj plán a zkuste to znovu.
Name
404 - Not Found
Description
input_task_id neodpovídá žádnému úkolu ve vašem účtu. Neexistující úkol a úkol patřící jinému účtu vrací stejnou odpověď. Zkontrolujte ID.
Name
429 - Too Many Requests
Description
Překročili jste limit rychlosti. Počkejte a zkuste to znovu. Viz Limity rychlosti.

GET/openapi/v1/image-to-image/:id

Získat úlohu Obrázek na obrázek

Vrátí úlohu Obrázek na obrázek podle jejího ID.

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

Parametry

Name
id
Type
path
Description
ID úlohy z odpovědi na vytvoření.

Návratová hodnota

Objekt úlohy Obrázek na obrázek.

DELETE/openapi/v1/image-to-image/:id

Delete an Image to Image task

Trvale odstraní úlohu Obrázek na obrázek, včetně jejích obrázků a dat. Odstranění nelze vrátit zpět.

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

Parametry cesty

Name
id
Type
path
Description
ID úlohy, která má být odstraněna.

Stav úlohy

Odstranění úlohy ve stavu PENDING vrátí kredity použité při jejím vytvoření.

Úlohu ve stavu IN_PROGRESS nelze odstranit. Požadavek vrátí 409 Conflict a úloha pokračuje v běhu. Meshy nevrací kredity za úlohu, která už byla spuštěna, takže její odstranění by vás stálo jak kredity, tak výsledek. Počkejte, až dosáhne stavu SUCCEEDED, FAILED nebo CANCELED, a teprve poté ji odstraňte.

Odstranění úlohy v konečném stavu (SUCCEEDED, FAILED nebo CANCELED) kredity nevrací.

Návratové hodnoty

200 OK při úspěšném odstranění úlohy, nebo 409 Conflict, pokud je úloha ve stavu IN_PROGRESS.

GET/openapi/v1/image-to-image

Seznam úloh Obrázek na obrázek

Vrátí seznam vašich úloh Obrázek na obrázek a Text na obrázek. Pole type u každé úlohy udává, o kterou ze dvou se jedná.

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

Parametry

Name
page_num
Type
integer
Description
Číslo stránky, která se má vrátit. Začíná na 1 a výchozí hodnota je 1.
Name
page_size
Type
integer
Description
Počet úloh na stránku, maximálně 100. Výchozí hodnota je 10.
Name
sort_by
Type
string
Description
Pořadí řazení.
Dostupné hodnoty:
- +created_at: nejstarší první
- -created_at: nejnovější první

Návratová hodnota

Stránkovaný seznam objektů úloh ve stejném formátu jako objekt úlohy Obrázek na obrázek.

GET/openapi/v1/image-to-image/:id/stream

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

Streamuje aktualizace úlohy Obrázek na obrázek jako Server-Sent Events (SSE).

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.
// These examples are shortened. Each event holds the full task object.
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=***"
  ]
}

Parametry

Name
id
Type
path
Description
ID úlohy z odpovědi na vytvoření.

Návratová hodnota

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

Každá událost obsahuje celý objekt úlohy, ve stejné podobě, jakou vrací koncový bod Get. Dokud je úloha ve stavu PENDING nebo IN_PROGRESS, její výsledková pole ještě nemají hodnoty.

Objekt úlohy Obrázek na obrázek

Objekt úlohy Obrázek na obrázek popisuje jeden obrázek vygenerovaný z referenčních obrázků a textového promptu. Obsahuje stav, progress a obrázky, jakmile úloha uspěje.

Vlastnosti

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,
  "image_urls": [
    "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
  ],
  "task_error": null,

  "consumed_credits": 3
}

Name
id
Type
string
Description
ID úlohy. Považujte jej za neprůhledný řetězec a nespoléhejte na jeho formát.
Name
type
Type
string
Description
Typ úlohy, vždy image-to-image.
Name
ai_model
Type
string
Description
AI model, který úloha použila.
Dostupné hodnoty:
- nano-banana
- nano-banana-2
- nano-banana-2-lite
- nano-banana-2-1
- nano-banana-pro
- gpt-image-2
- gpt-image-2-5-flare
- gpt-image-2-5-sunburst
Name
prompt
Type
string
Description
Textový prompt, kterým se úprava řídila.
Name
status
Type
string
Description
Stav úlohy, jedna z hodnot PENDING, IN_PROGRESS, SUCCEEDED, FAILED nebo CANCELED.
Name
progress
Type
integer
Description
Jak velká část úlohy je hotová, v procentech. Je 0, dokud úloha nezačne, a 100, jakmile uspěje.
Name
created_at
Type
timestamp
Description
Čas vytvoření úlohy, v milisekundách Unix.
Name
started_at
Type
timestamp
Description
Čas zahájení úlohy, v milisekundách Unix. Chybí, dokud úloha nezačne.
Name
finished_at
Type
timestamp
Description
Čas dokončení úlohy, v milisekundách Unix. Chybí, dokud úloha neskončí.
Name
expires_at
Type
timestamp
Description
Čas vypršení platnosti výsledků úlohy, v milisekundách Unix. Chybí, dokud úloha neskončí.
Name
preceding_tasks
Type
integer
Description
Počet úloh před touto úlohou ve frontě. Hodnota má smysl pouze tehdy, když je úloha ve stavu PENDING. Pole se vynechává, pokud je hodnota 0.
Name
image_urls
Type
array
Description
Adresy URL pro stažení vygenerovaných obrázků. Při generate_multi_view: true obsahuje jednu URL na pohled, obvykle tři. Pokud Meshy nedokáže oddělit každý pohled, vrátí jich méně a úloha přesto uspěje. Jinak obsahuje jednu URL.
Name
task_error
Type
object
Description
Podrobnosti o chybě, pokud úloha selže. Je null, pokud stav není FAILED. Viz Chyby.
Name
consumed_credits
Type
integer
Description
Počet kreditů, které úloha spotřebovala. Přítomno, pokud je stav PENDING, IN_PROGRESS nebo SUCCEEDED. U úlohy se stavem FAILED je 0, protože Meshy v případě selhání úlohy kredity vrací.