Obraz na obraz API

Obraz na obraz API to funkcja, która umożliwia zintegrowanie możliwości edycji obrazów AI firmy Meshy z własną aplikacją. Przekształcaj i edytuj istniejące obrazy, korzystając z obrazów referencyjnych i podpowiedzi tekstowych dzięki naszym zaawansowanym modelom AI.

Ten punkt końcowy generuje obrazy. Jeśli celem jest obiekt, który można trzymać w ręku lub wydrukować — brelok, magnes na lodówkę, figurkę, lampę lub keycap na podstawie zdjęcia — skorzystaj z Creative Lab API (obraz prototypu → budowa modelu 3D). Jeśli celem jest model 3D przedstawiający to, co znajduje się na obrazie, skorzystaj z Obraz na 3D.

POST/openapi/v1/image-to-image

Create an Image to Image Task

Ten punkt końcowy umożliwia utworzenie nowego zadania Obraz na obraz. Zapoznaj się z The Image to Image Task Object, aby zobaczyć, jakie właściwości zawiera obiekt zadania Obraz na obraz.

Zadanie jest wykonywane w tle. Informacje o tym, jak długo zwykle to trwa, znajdziesz w Processing Times.

Parametry

Name
ai_model
Type
string
Wymagane
Description
ID modelu używanego do generowania obrazu.
Dostępne wartości:
- nano-banana: model standardowy (3 kredyty za obraz)
- nano-banana-2: model zrównoważony o większych możliwościach niż standardowy (6 kredytów za obraz)
- nano-banana-2-lite: lżejsza wersja nano-banana-2 (3 kredyty za obraz)
- nano-banana-pro: model Pro o podwyższonej jakości (9 kredytów za obraz)
- gpt-image-2: OpenAI GPT Image 2, wysokiej jakości model edycji obrazów (12 kredytów za obraz)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), wysokiej jakości model edycji obrazów (12 kredytów za obraz)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), wysokiej jakości model edycji obrazów (12 kredytów za obraz)
Name
prompt
Type
string
Wymagane
Description
Opis tekstowy transformacji lub edycji, którą chcesz zastosować do obrazów referencyjnych.

Wymagany jest tylko jeden z parametrów input_task_id lub reference_image_urls. Jeśli podane zostaną oba, priorytet ma input_task_id.

Name
input_task_id
Type
string
Wymagane
Description
ID zakończonego zadania generowania obrazu, którego obrazy wyjściowe mają zostać użyte jako obrazy referencyjne. To zadanie musi być jednym z następujących typów: Tekst na obraz lub Obraz na obraz, w tym ich warianty Wiele widoków. Dodatkowo musi zostać uruchomione za pośrednictwem API i mieć status SUCCEEDED.
Wykorzystywane są wszystkie obrazy wyjściowe zadania źródłowego. Zadanie z pojedynczym obrazem dostarcza 1 obraz referencyjny; zadanie typu Wiele widoków dostarcza po jednym obrazie na każdy wygenerowany widok, dzięki czemu pojedyncze ID zadania może wypełnić kilka z 5 miejsc na obrazy referencyjne.
Zadanie źródłowe musi nadal mieścić się w okresie przechowywania zasobów — po jego upływie odwołanie się do jego ID zwraca 404.

Name
reference_image_urls
Type
array
Wymagane
Description
Tablica od 1 do 5 obrazów referencyjnych używanych w zadaniu edycji obrazu. Obecnie obsługujemy formaty .jpg, .jpeg, .png i .webp.
Maksymalny rozmiar pliku: 20 MB na obraz.
Istnieją dwa sposoby dostarczenia każdego obrazu:
- Publicznie dostępny URL: adres URL dostępny z poziomu publicznego internetu.
- Data URI: zakodowany w base64 identyfikator URI danych obrazu. Przykład Data URI: data:image/jpeg;base64,<your base64-encoded image data>.

Name
generate_multi_view
Type
boolean
domyślne false
Description
Gdy ustawione na true, generuje obraz wielowidokowy przedstawiający obiekt z wielu kątów.
Gdy generate_multi_view ma wartość true, parametru aspect_ratio nie można ustawić.
Name
aspect_ratio
Type
string
domyślne 1:1
Description
Określ proporcje obrazu wyjściowego. Dozwolone wartości zależą od wybranego 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
Dostępne wartości:
- 1:1: format kwadratowy
- 16:9: panorama pozioma
- 9:16: panorama pionowa
- 4:3: standardowy format poziomy
- 3:4: standardowy format pionowy
- 3:2: format poziomy (obsługiwany tylko przez modele GPT Image)
- 2:3: format pionowy (obsługiwany tylko przez modele GPT Image)
Name
remove_background
Type
boolean
domyślne false
Description
Gdy ustawione na true, obraz wyjściowy jest zwracany jako przezroczysty plik PNG RGBA z usuniętym tłem, dzięki czemu można zestawić obiekt z dowolnym tłem.

Zwracane dane

Właściwość result w odpowiedzi zawiera id zadania nowo utworzonego zadania Obraz na obraz.

Tryby niepowodzenia

Name
400 - Bad Request
Description
Żądanie było niedopuszczalne. Typowe przyczyny:
- Brakujący parametr: brakuje wymaganego parametru (np. ai_model, prompt) lub nie podano ani reference_image_urls, ani input_task_id.
- Nieprawidłowe zadanie wejściowe: input_task_id musi odnosić się do zadania Tekst na obraz lub Obraz na obraz (w tym Wiele widoków) o statusie SUCCEEDED, które nadal posiada wyniki w postaci obrazów. Zadanie innego typu, takie, które się nie powiodło, lub takie, którego wszystkie obrazy wygasły, jest odrzucane.
- Nieprawidłowy format obrazu: jeden lub więcej obrazów referencyjnych ma nieobsługiwany format.
- Niedostępny URL: nie udało się pobrać jednego lub więcej reference_image_urls.
- Zbyt duży obraz: jeden lub więcej obrazów reference_image_urls przekracza 20 MB.
- Nieprawidłowy parametr: aspect_ratio nie znajduje się wśród dozwolonych wartości dla wybranego ai_model.
- Konflikt: generate_multi_view i aspect_ratio nie mogą być używane jednocześnie.
Name
401 - Unauthorized
Description
Uwierzytelnianie nie powiodło się. Sprawdź swój klucz API.
Name
402 - Payment Required
Description
Niewystarczająca liczba kredytów do wykonania tego zadania.
Name
404 - Not Found
Description
input_task_id nie odnosi się do zadania należącego do Twojego konta. Zadanie, które nie istnieje, oraz zadanie należące do innego konta zwracają tę samą odpowiedź.
Name
429 - Too Many Requests
Description
Przekroczono limit szybkości.

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

Retrieve an Image to Image Task

Ten punkt końcowy umożliwia pobranie zadania Obraz na obraz na podstawie prawidłowego id zadania. Zapoznaj się z sekcją Obiekt zadania Obraz na obraz, aby zobaczyć, jakie właściwości są zawarte w obiekcie zadania Obraz na obraz.

Parametry

Name
id
Type
path
Description
Unikalny identyfikator zadania Obraz na obraz do pobrania.

Zwracane dane

Odpowiedź zawiera obiekt zadania Obraz na obraz. Szczegóły znajdziesz w sekcji Obiekt zadania Obraz na obraz.

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

Usuwanie zadania Obraz na obraz

Ten punkt końcowy trwale usuwa zadanie Obraz na obraz, wraz ze wszystkimi powiązanymi obrazami i danymi. Ta czynność jest nieodwracalna.

Parametry ścieżki

Name
id
Type
path
Description
Identyfikator zadania Obraz na obraz do usunięcia.

Status zadania

Zadanie, które nadal ma status PENDING, jest usuwane, a kredyty zużyte w momencie utworzenia są zwracane.

Zadanie, które ma już status IN_PROGRESS, nie może zostać usunięte: żądanie jest odrzucane z kodem 409 Conflict, a zadanie nadal się wykonuje. Kredyty za zadanie, które worker już rozpoczął, nie podlegają zwrotowi, więc usunięcie go w trakcie wykonywania kosztowałoby Cię zarówno kredyty, jak i wynik. Poczekaj, aż osiągnie status SUCCEEDED, FAILED lub CANCELED, a następnie je usuń.

Zadanie w stanie końcowym (SUCCEEDED, FAILED lub CANCELED) jest usuwane bez zwrotu kredytów.

Zwraca

Zwraca 200 OK w przypadku powodzenia lub 409 Conflict, gdy zadanie ma status 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

Wyświetl listę zadań Obraz na obraz

Ten punkt końcowy umożliwia pobranie listy zadań Obraz na obraz.

Parametry

Name
page_num
Type
integer
Description
Numer strony do stronicowania. Zaczyna się od 1 i taka jest wartość domyślna.
Name
page_size
Type
integer
Description
Limit rozmiaru strony. Domyślnie 10 elementów. Maksymalna dozwolona wartość to 100 elementów.
Name
sort_by
Type
string
Description
Pole, według którego ma nastąpić sortowanie. Dostępne wartości:
- +created_at: Sortuj według czasu utworzenia rosnąco.
- -created_at: Sortuj według czasu utworzenia malejąco.

Zwraca

Zwraca stronicowaną listę obiektów zadania Obraz na obraz.

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

Przesyłaj strumieniowo zadanie Obraz na obraz

Ten punkt końcowy przesyła strumieniowo aktualizacje w czasie rzeczywistym dla zadania Obraz na obraz przy użyciu Server-Sent Events (SSE).

Parametry

Name
id
Type
path
Description
Unikalny identyfikator zadania Obraz na obraz do przesyłania strumieniowego.

Zwraca

Zwraca strumień obiektów zadania Obraz na obraz jako Server-Sent Events.

Dla zadań w stanie PENDING lub IN_PROGRESS strumień odpowiedzi będzie zawierał tylko niezbędne pola progress i 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=***"
  ]
}

The Image to Image Task Object

Obiekt Image to Image Task to jednostka pracy śledzona przez Meshy w celu wygenerowania obrazu na podstawie obrazów referencyjnych oraz wprowadzonego promptu tekstowego. Obiekt ma następujące właściwości:

Properties

Name
id
Type
string
Description
Unikalny identyfikator zadania. Chociaż jako szczegół implementacyjny dla identyfikatorów zadań używamy k-sortowalnego UUID, nie powinno się przyjmować żadnych założeń co do formatu id.
Name
type
Type
string
Description
Typ zadania generowania obrazu. Dla zadań Image to Image zawsze będzie to image-to-image.
Name
ai_model
Type
string
Description
Model AI użyty do tego zadania. Możliwe wartości to nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro, gpt-image-2, gpt-image-2-5-flare lub gpt-image-2-5-sunburst.
Name
prompt
Type
string
Description
Prompt tekstowy, który został użyty do ukierunkowania transformacji obrazu.
Name
status
Type
string
Description
Status zadania. Możliwe wartości to jedna z: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Postęp zadania. Jeśli zadanie nie zostało jeszcze rozpoczęte, ta właściwość będzie wynosić 0. Gdy zadanie zakończy się powodzeniem, stanie się 100.
Name
created_at
Type
timestamp
Description
Znacznik czasu utworzenia zadania, w milisekundach.
Znacznik czasu reprezentuje liczbę milisekund, która upłynęła od 1 stycznia 1970 UTC, zgodnie ze standardem RFC 3339. Na przykład piątek, 1 września 2023, 12:00:00 czasu GMT jest reprezentowany jako 1693569600000. Dotyczy to wszystkich znaczników czasu w Meshy API.
Name
started_at
Type
timestamp
Description
Znacznik czasu rozpoczęcia zadania, w milisekundach. Jeśli zadanie nie zostało jeszcze rozpoczęte, ta właściwość będzie wynosić 0.
Name
finished_at
Type
timestamp
Description
Znacznik czasu zakończenia zadania, w milisekundach. Jeśli zadanie nie zostało jeszcze zakończone, ta właściwość będzie wynosić 0.
Name
expires_at
Type
timestamp
Description
Znacznik czasu wygaśnięcia wyniku zadania, w milisekundach.
Name
preceding_tasks
Type
integer
Description
Liczba poprzedzających zadań.
Wartość tego pola ma znaczenie tylko wtedy, gdy status zadania to PENDING.
Name
image_urls
Type
array
Description
Tablica adresów URL do pobrania wygenerowanych obrazów. Gdy włączona jest opcja generate_multi_view, tablica ta zawiera trzy adresy URL obrazów reprezentujące różne kąty widzenia. W przeciwnym razie zawiera pojedynczy adres URL obrazu.
Name
task_error
Type
object
Description
Szczegóły błędu dla nieudanych zadań. Pełny opis obiektu task_error znajdziesz w sekcji Błędy.
Name
consumed_credits
Type
integer
Description
Liczba kredytów zużytych przez to zadanie. Obecna, gdy status zadania to PENDING, IN_PROGRESS lub SUCCEEDED. Zwraca 0 dla zadań FAILED (kredyty są zwracane w przypadku niepowodzenia).

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
}