Obrázek na obrázek API

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

POST/openapi/v1/image-to-image

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

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

Parametry

  • Name
    ai_model
    Type
    string
    Povinné
    Description

    ID modelu, který se použije pro generování obrázků.

    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 pro úpravy obrázků s vysokou věrností (12 kreditů za obrázek)
  • Name
    prompt
    Type
    string
    Povinné
    Description

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

  • Name
    reference_image_urls
    Type
    array
    Povinné
    Description

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

    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: Base64-kódovaný Data URI 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

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

    Pokud 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 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

    Pokud 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 objekt složit na jakékoli pozadí.

Návratové hodnoty

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

Chybové režimy

  • 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, reference_image_urls).
    • Neplatný formát obrázku: Jeden nebo více referenčních obrázků nejsou podporované formáty.
    • Nepřístupná URL: Jedna nebo více reference_image_urls nemohly být staženy.
    • 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

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

Odpověď

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

Načtení úkolu Obrázek na obrázek

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

Parametry

  • Name
    id
    Type
    path
    Description

    Jedinečný identifikátor pro úkol Obrázek na obrázek, který chcete načíst.

Vrací

Odpověď obsahuje objekt úkolu Obrázek na obrázek. Podívejte se do sekce Objekt úkolu Obrázek na obrázek pro podrobnosti.

Požadavek

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

Odpověď

{
  "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, kterou chcete smazat.

Vrátí

Vrátí 200 OK v případě úspěchu.

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

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

Seznam úkolů Obrázek na obrázek

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

  • Name
    sort_by
    Type
    string
    Description

    Pole pro třídění. Dostupné hodnoty:

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

Vrací

Vrací stránkovaný seznam Objektů úkolů Obrázek na obrázek.

Požadavek

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

Odpověď

[
  {
    "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 v reálném čase pro úlohu Obrázek na obrázek pomocí Server-Sent Events (SSE).

Parametry

  • Name
    id
    Type
    path
    Description

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

Vrací

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

Pro úlohy PENDING nebo IN_PROGRESS bude stream 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, aby vygeneroval obrázek 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. 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 Obrázek na obrázek to 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-pro nebo gpt-image-2.

  • Name
    prompt
    Type
    string
    Description

    Textový prompt, který byl použit k vedení 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

    Pokrok ú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 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, 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 na vygenerované obrázky. Když je povoleno generate_multi_view, toto pole obsahuje tři URL obrázků představující různé úhly pohledu. Jinak obsahuje jedno URL obrázku.

  • Name
    task_error
    Type
    object
    Description

    Podrobnosti o chybě pro neúspěšné úlohy. Viz Chyby pro úplnou referenci objektu 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 Obrázek na obrázek

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