Obraz na obraz API

Obraz na obraz API to funkcja, która umożliwia zintegrowanie możliwości edycji obrazów AI Meshy z Twoją własną aplikacją. Przekształcaj i edytuj istniejące obrazy, korzystając z obrazów referencyjnych oraz podpowiedzi tekstowych za pomocą naszych zaawansowanych modeli AI.

POST/openapi/v1/image-to-image

Utwórz zadanie Obraz na obraz

Ten punkt końcowy pozwala utworzyć nowe zadanie Obraz na obraz. Zobacz Obiekt zadania Obraz na obraz, aby dowiedzieć się, jakie właściwości zawiera obiekt zadania Obraz na obraz.

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-pro: Model Pro o podwyższonej jakości (9 kredytów za obraz)
- gpt-image-2: OpenAI GPT Image 2, model edycji obrazu o wysokiej wierności (12 kredytów za obraz)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), model edycji obrazu o wysokiej wierności (12 kredytów za obraz)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), model edycji obrazu o wysokiej wierności (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 podano oba, priorytet ma input_task_id.

Name
input_task_id
Type
string
Wymagane
Description
ID ukoń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 w trybie Wiele widoków. Ponadto musi zostać uruchomione za pośrednictwem API i mieć status SUCCEEDED.
Używane są wszystkie obrazy wyjściowe zadania źródłowego. Zadanie z pojedynczym obrazem dostarcza 1 obraz referencyjny; zadanie w trybie Wiele widoków dostarcza po jednym obrazie na każdy wygenerowany widok, więc jedno ID zadania może wypełnić kilka z 5 dostępnych miejsc na obrazy referencyjne.
Zadanie źródłowe musi nadal znajdować się w okresie przechowywania zasobów — po jego wygaśnięciu jego ID zwraca 404.

Name
reference_image_urls
Type
array
Wymagane
Description
Tablica od 1 do 5 obrazów referencyjnych używanych do zadania edycji obrazu. Obecnie obsługujemy formaty .jpg, .jpeg i .png.
Istnieją dwa sposoby dostarczenia każdego obrazu:
- Publicznie dostępny URL: Adres URL dostępny z 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 w trybie Wiele widoków, pokazujący obiekt z wielu kątów.
Gdy generate_multi_view ma wartość true, nie można ustawić parametru aspect_ratio.
Name
aspect_ratio
Type
string
domyślne 1:1
Description
Określa proporcje obrazu wyjściowego. Dozwolone wartości zależą od wybranego ai_model:
- nano-banana, nano-banana-2, 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: Panoramiczny poziomy
- 9:16: Panoramiczny pionowy
- 4:3: Standardowy poziomy
- 3:4: Standardowy pionowy
- 3:2: Poziomy (obsługiwany tylko przez modele GPT Image)
- 2:3: 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 w formacie RGBA z usuniętym tłem, dzięki czemu możesz umieścić obiekt na dowolnym tle.

Zwracane wartości

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

Tryby niepowodzenia

Name
400 - Bad Request
Description
Żądanie było niepoprawne. Typowe przyczyny:
- Brakujący parametr: Brak 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 wskazywać na zadanie Tekst na obraz lub Obraz na obraz (w tym w trybie Wiele widoków) o statusie SUCCEEDED, które nadal posiada wyniki w postaci obrazów. Zadanie innego typu, takie, które nie zakończyło się powodzeniem, 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.
- Nieprawidłowy parametr: aspect_ratio nie jest jedną z 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 wskazuje na zadanie należące 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 zadania Obraz na obraz to jednostka pracy śledzona przez Meshy w celu wygenerowania obrazu na podstawie obrazów referencyjnych oraz danych wejściowych w postaci promptu tekstowego. Obiekt ma następujące właściwości:

Właściwości

Name
id
Type
string
Description
Unikalny identyfikator zadania. Chociaż jako szczegół implementacyjny używamy identyfikatorów zadań w formacie UUID z możliwością sortowania k-sortable, nie należy przyjmować żadnych założeń dotyczących formatu tego identyfikatora.
Name
type
Type
string
Description
Typ zadania generowania obrazu. Dla zadań Obraz na obraz 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-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 sterowania transformacją 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 miała wartość 0. Gdy zadanie zakończy się powodzeniem, wartość ta zmieni się na 100.
Name
created_at
Type
timestamp
Description
Znacznik czasu utworzenia zadania, w milisekundach.
Znacznik czasu reprezentuje liczbę milisekund, które upłynęły od 1 stycznia 1970 UTC, zgodnie ze standardem RFC 3339. Na przykład piątek, 1 września 2023, godzina 12:00:00 czasu GMT jest reprezentowana 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 miała wartość 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 miała wartość 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 jeden 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. Występuje, 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
}