Obraz na obraz API

Edytuj i przekształcaj obrazy we własnej aplikacji. Wyślij obrazy referencyjne oraz prompt tekstowy, a modele AI Meshy wygenerują na ich podstawie nowy obraz.

Obraz na obraz tworzy obrazy. Aby utworzyć model 3D na podstawie tego, co znajduje się na obrazie, użyj Obraz na 3D. Aby na podstawie zdjęcia utworzyć obiekt, który można trzymać w ręku lub wydrukować, użyj API Creative Lab. Tworzą one obraz prototypu, a następnie na jego podstawie budują model 3D, na przykład brelok, magnes na lodówkę, figurkę, lampę lub keycap.

POST/openapi/v1/image-to-image

Utwórz zadanie Obraz na obraz

Tworzy zadanie Obraz na obraz. Zadanie wykonuje się w tle. Informacje o typowym czasie trwania zadania znajdziesz w sekcji Czasy przetwarzania.

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
Wymagane
Description
Model AI generujący obraz. Ceny różnią się w zależności od modelu. Zobacz Cennik.
Dostępne wartości:
- nano-banana: model standardowy
- nano-banana-2: bardziej zaawansowany niż nano-banana
- nano-banana-2-lite: lekka wersja nano-banana-2
- nano-banana-2-1: Nano Banana 2.1
- nano-banana-pro: model Pro, o wyższej jakości. Wymaga planu Pro lub wyższego. Przy niższym planie zwraca 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
Wymagane
Description
Tekst opisujący edycję lub transformację, jaką należy zastosować do obrazów referencyjnych.

Name
input_task_id
Type
string
Wymagane
Description
Wymagane, chyba że wysyłasz reference_image_urls. ID zadania Tekst na obraz lub Obraz na obraz, którego obrazy mają posłużyć jako referencje, w tym zadań z wieloma widokami. Zadanie musi być utworzone przez Ciebie za pomocą API i mieć status SUCCEEDED.
Meshy wykorzystuje każdy obraz wygenerowany przez zadanie. Zadanie z pojedynczym obrazem dostarcza jeden obraz referencyjny, a zadanie z wieloma widokami dostarcza po jednym na każdy widok. Dzięki temu jedno ID zadania może wypełnić kilka z pięciu dostępnych miejsc na obrazy referencyjne.
Zadanie musi nadal mieścić się w okresie przechowywania zasobów. Po jego wygaśnięciu podanie tego ID zwraca 404.

Name
reference_image_urls
Type
array
Wymagane
Description
Wymagane, chyba że wysyłasz input_task_id. Od jednego do pięciu obrazów referencyjnych do edycji, każdy jako publiczny URL lub Data URI, na przykład data:image/jpeg;base64,<zakodowane w base64 dane obrazu>. Pusta tablica lub więcej niż pięć obrazów zwraca 400. Jeśli wyślesz oba parametry, Meshy użyje input_task_id.
Każdy obraz musi być plikiem .jpg, .jpeg, .png lub .webp o rozmiarze maksymalnie 20 MB i co najmniej 32 pikselach z każdej strony.

Name
generate_multi_view
Type
boolean
domyślne false
Description
Czy wygenerować obraz z wieloma widokami, pokazujący obiekt z kilku kątów. Gdy ustawione na true, nie możesz wysyłać aspect_ratio. Wysłanie obu parametrów zwraca 400.
Name
aspect_ratio
Type
string
domyślne 1:1
Description
Proporcje obrazu wyjściowego. Wartości, które możesz wysłać, zależą od ai_model.
Dostępne wartości:
- 1:1: kwadrat
- 16:9: panorama pozioma
- 9:16: panorama pionowa
- 4:3: standardowy poziomy
- 3:4: standardowy pionowy
- 3:2: poziomy, tylko dla modeli GPT Image
- 2:3: pionowy, tylko dla modeli GPT Image
Modele GPT Image to gpt-image-2, gpt-image-2-5-flare i gpt-image-2-5-sunburst. Przy modelu nano-banana wartości 3:2 i 2:3 zwracają 400.
Name
remove_background
Type
boolean
domyślne false
Description
Czy usunąć tło. Gdy ustawione na true, Meshy zwraca obraz wyjściowy jako przezroczysty plik PNG RGBA, dzięki czemu możesz umieścić obiekt na dowolnym tle.

Zwracane wartości

Pole result odpowiedzi zawiera ID nowego zadania Obraz na obraz.

Tryby błędów

Name
400 - Bad Request
Description
Żądanie nie może zostać wykonane. Komunikat błędu wskazuje, jaki problem został znaleziony. Na przykład:
- Brakujący parametr: Brakuje wymaganego parametru, takiego jak ai_model lub prompt, albo nie wysłano ani reference_image_urls, ani input_task_id.
- Nieprawidłowe zadanie wejściowe: input_task_id nie wskazuje na możliwe do użycia zadanie. Musi to być zadanie Tekst na obraz lub Obraz na obraz ze statusem SUCCEEDED, w tym zadanie z wieloma widokami, które nadal posiada obrazy wyjściowe. Meshy odrzuca zadanie innego typu, zadanie, które się nie powiodło, oraz zadanie, którego obrazy całkowicie wygasły.
- Nieprawidłowy format obrazu: Jeden lub więcej obrazów referencyjnych ma nieobsługiwany format.
- Nieosiągalny URL: Meshy nie może pobrać jednego lub więcej obrazów reference_image_urls.
- Obraz zbyt duży: Jeden lub więcej obrazów reference_image_urls przekracza 20 MB.
- Obraz zbyt mały: Jeden lub więcej obrazów reference_image_urls ma bok krótszy niż 32 piksele.
- Nieprawidłowy parametr: aspect_ratio nie jest jedną z wartości obsługiwanych przez wybrany ai_model.
- Konflikt: Żądanie wysyła aspect_ratio razem z generate_multi_view: true.
Popraw żądanie i wyślij je ponownie. Zobacz Błędy.
Name
401 - Unauthorized
Description
Klucz API jest nieprawidłowy lub go brakuje. Sprawdź nagłówek Authorization.
Name
402 - Payment Required
Description
Konto nie może wykonać tego zadania. Na przykład:
- Plan darmowy: Utworzenie zadania wymaga płatnego planu. Zaktualizuj swój plan w ustawieniach subskrypcji, a następnie spróbuj ponownie.
- Niewystarczające kredyty: Konto nie ma wystarczającej liczby kredytów na to zadanie lub konto osiągnęło limit kredytów.
- Wymagany plan: Żądanie używa nano-banana-pro na planie niższym niż Pro.
Sprawdź saldo kredytów oraz plan, a następnie spróbuj ponownie.
Name
404 - Not Found
Description
input_task_id nie pasuje do żadnego zadania na Twoim koncie. Zadanie, które nie istnieje, oraz zadanie należące do innego konta zwracają tę samą odpowiedź. Sprawdź ID.
Name
429 - Too Many Requests
Description
Przekroczono limit szybkości. Poczekaj, a następnie spróbuj ponownie. Zobacz Limity szybkości.

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

Pobierz zadanie Obraz na obraz

Zwraca zadanie Obraz na obraz na podstawie jego 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 zadania pochodzące z odpowiedzi tworzenia.

Zwraca

Obiekt zadania Obraz na obraz.

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

Usuń zadanie Obraz na obraz

Trwale usuwa zadanie Obraz na obraz, w tym jego obrazy i dane. Usunięcia nie można cofnąć.

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 ścieżki

Name
id
Type
path
Description
ID zadania do usunięcia.

Status zadania

Usunięcie zadania o statusie PENDING zwraca kredyty wykorzystane podczas jego tworzenia.

Zadania o statusie IN_PROGRESS nie można usunąć. Żądanie zwraca 409 Conflict, a zadanie nadal się wykonuje. Meshy nie zwraca kredytów za zadanie, które już się rozpoczęło, więc jego usunięcie kosztowałoby Cię zarówno kredyty, jak i wynik. Poczekaj, aż osiągnie status SUCCEEDED, FAILED lub CANCELED, a następnie je usuń.

Usunięcie zadania o statusie końcowym (SUCCEEDED, FAILED lub CANCELED) nie powoduje zwrotu kredytów.

Zwraca

200 OK, gdy zadanie zostało usunięte, lub 409 Conflict, gdy zadanie ma status IN_PROGRESS.

GET/openapi/v1/image-to-image

Lista zadań Obraz na obraz

Zwraca listę Twoich zadań Obraz na obraz i Tekst na obraz. Pole type każdego zadania określa, do którego z tych dwóch typów ono należy.

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
Numer strony do zwrócenia. Zaczyna się od 1 i domyślnie przyjmuje tę wartość.
Name
page_size
Type
integer
Description
Liczba zadań na stronę, maksymalnie 100. Domyślnie 10.
Name
sort_by
Type
string
Description
Kolejność sortowania.
Dostępne wartości:
- +created_at: od najstarszych
- -created_at: od najnowszych

Zwraca

Stronicowaną listę obiektów zadań, w tym samym formacie co obiekt zadania Obraz na obraz.

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

Strumieniowanie zadania Obraz na obraz

Strumieniuje aktualizacje zadania Obraz na obraz jako zdarzenia 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 zadania z odpowiedzi utworzenia.

Zwraca

Strumień obiektów zadania Obraz na obraz jako zdarzenia Server-Sent Events.

Każde zdarzenie zawiera pełny obiekt zadania, w tej samej postaci, jaką zwraca punkt końcowy Get. Gdy zadanie ma status PENDING lub IN_PROGRESS, jego pola wynikowe nie mają jeszcze wartości.

Obiekt zadania Image to Image

Obiekt zadania Image to Image opisuje jeden obraz wygenerowany na podstawie obrazów referencyjnych i promptu tekstowego. Przechowuje status, progress oraz obrazy, gdy zadanie zakończy się sukcesem.

Właściwości

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 zadania. Traktuj je jako nieprzezroczysty ciąg znaków i nie polegaj na jego formacie.
Name
type
Type
string
Description
Typ zadania, zawsze image-to-image.
Name
ai_model
Type
string
Description
Model AI użyty przez zadanie.
Dostępne wartości:
- 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
Prompt tekstowy, który kierował edycją.
Name
status
Type
string
Description
Status zadania, jeden z: PENDING, IN_PROGRESS, SUCCEEDED, FAILED lub CANCELED.
Name
progress
Type
integer
Description
Jaka część zadania jest wykonana, w procentach. Wynosi 0, dopóki zadanie się nie rozpocznie, i 100, gdy zakończy się sukcesem.
Name
created_at
Type
timestamp
Description
Czas utworzenia zadania, w milisekundach Unix.
Name
started_at
Type
timestamp
Description
Czas rozpoczęcia zadania, w milisekundach Unix. Nieobecny, dopóki zadanie się nie rozpocznie.
Name
finished_at
Type
timestamp
Description
Czas zakończenia zadania, w milisekundach Unix. Nieobecny, dopóki zadanie się nie zakończy.
Name
expires_at
Type
timestamp
Description
Czas wygaśnięcia wyników zadania, w milisekundach Unix. Nieobecny, dopóki zadanie się nie zakończy.
Name
preceding_tasks
Type
integer
Description
Liczba zadań znajdujących się przed tym zadaniem w kolejce. Wartość ma znaczenie tylko wtedy, gdy zadanie ma status PENDING. Pole jest pomijane, gdy wartość wynosi 0.
Name
image_urls
Type
array
Description
Adresy URL do pobrania wygenerowanych obrazów. Przy generate_multi_view: true zawiera po jednym adresie URL na widok, zwykle trzy. Jeśli Meshy nie może rozdzielić wszystkich widoków, zwraca ich mniej, a zadanie i tak kończy się sukcesem. W przeciwnym razie zawiera jeden adres URL.
Name
task_error
Type
object
Description
Szczegóły błędu, gdy zadanie zakończy się niepowodzeniem. Ma wartość null, chyba że status to FAILED. Zobacz Błędy.
Name
consumed_credits
Type
integer
Description
Liczba kredytów zużytych przez zadanie. Obecne, gdy status to PENDING, IN_PROGRESS lub SUCCEEDED. Wynosi 0 dla zadania ze statusem FAILED, ponieważ Meshy zwraca kredyty, gdy zadanie zakończy się niepowodzeniem.