Obraz na obraz API

Obraz na obraz API to funkcja, która pozwala na integrację możliwości edycji obrazów AI Meshy z Twoją własną aplikacją. Przekształcaj i edytuj istniejące obrazy, używając obrazów referencyjnych i podpowiedzi tekstowych z naszymi potężnymi modelami AI.

POST/openapi/v1/image-to-image

Utwórz zadanie Obraz na obraz

Ten punkt końcowy pozwala na utworzenie nowego zadania Obraz na obraz. Odnieś się do Obiekt zadania Obraz na obraz, aby zobaczyć, które właściwości są zawarte w obiekcie zadania Obraz na obraz.

Parametry

Name
ai_model
Type
string
Wymagane
Description
ID modelu do użycia przy generowaniu obrazu.
Dostępne wartości:
- nano-banana: Standardowy model (3 kredyty za obraz)
- nano-banana-2: Zrównoważony model z większymi możliwościami niż standardowy (6 kredytów za obraz)
- nano-banana-pro: Model Pro z ulepszoną 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)
Name
prompt
Type
string
Wymagane
Description
Opis tekstowy transformacji lub edycji, którą chcesz zastosować do obrazów referencyjnych.
Name
reference_image_urls
Type
array
Wymagane
Description
Tablica od 1 do 5 obrazów referencyjnych do użycia w zadaniu edycji obrazu. Obecnie obsługujemy formaty .jpg, .jpeg i .png.
Istnieją dwa sposoby dostarczenia każdego obrazu:
- Publicznie dostępny URL: URL, który jest dostępny z publicznego internetu.
- Data URI: Zakodowany w base64 Data URI 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 z wieloma widokami pokazujący temat z różnych kątów.
Gdy generate_multi_view jest true, parametr aspect_ratio nie może być ustawiony.
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-pro: 1:1, 16:9, 9:16, 4:3, 3:4
- gpt-image-2: 1:1, 16:9, 9:16, 3:2, 2:3
Dostępne wartości:
- 1:1: Format kwadratowy
- 16:9: Szerokoekranowy krajobraz
- 9:16: Szerokoekranowy portret
- 4:3: Standardowy krajobraz (nieobsługiwany przez gpt-image-2)
- 3:4: Standardowy portret (nieobsługiwany przez gpt-image-2)
- 3:2: Krajobraz (obsługiwany tylko przez gpt-image-2)
- 2:3: Portret (obsługiwany tylko przez gpt-image-2)
Name
remove_background
Type
boolean
domyślne false
Description
Gdy ustawione na true, obraz wyjściowy jest zwracany jako przezroczysty RGBA PNG z usuniętym tłem, dzięki czemu można umieścić temat na dowolnym tle.

Zwraca

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

Tryby awarii

Name
400 - Bad Request
Description
Żądanie było nieakceptowalne. Typowe przyczyny:
- Brakujący parametr: Brakuje wymaganego parametru (np. ai_model, prompt, reference_image_urls).
- Nieprawidłowy format obrazu: Jeden lub więcej obrazów referencyjnych ma nieobsługiwany format.
- Nieosiągalny URL: Jeden lub więcej reference_image_urls nie mogło zostać pobranych.
- 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ę. Proszę sprawdzić swój klucz API.
Name
402 - Payment Required
Description
Niewystarczająca liczba kredytów do wykonania tego zadania.
Name
429 - Too Many Requests
Description
Przekroczyłeś swój 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}"
    ]
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

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

Pobierz zadanie Obraz na obraz

Ten punkt końcowy pozwala na pobranie zadania Obraz na obraz, podając prawidłowy id zadania. Odwołaj się do Obiekt zadania Obraz na obraz, aby zobaczyć, które właściwości są zawarte w obiekcie zadania Obraz na obraz.

Parametry

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

Zwraca

Odpowiedź zawiera obiekt zadania Obraz na obraz. Sprawdź sekcję Obiekt zadania Obraz na obraz dla szczegółów.

Żądanie

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

Odpowiedź

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

Usuń zadanie Obraz na obraz

Ten punkt końcowy trwale usuwa zadanie Obraz na obraz, w tym wszystkie powiązane obrazy i dane. Ta akcja jest nieodwracalna.

Parametry ścieżki

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

Zwraca

Zwraca 200 OK w przypadku sukcesu.

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

Lista zadań Obraz na obraz

Ten punkt końcowy pozwala na pobranie listy zadań Obraz na obraz.

Parametry

Name
page_num
Type
integer
Description
Numer strony dla stronicowania. Zaczyna się i domyślnie wynosi 1.
Name
page_size
Type
integer
Description
Limit rozmiaru strony. Domyślnie wynosi 10 pozycji. Maksymalnie dozwolone to 50 pozycji.
Name
sort_by
Type
string
Description
Pole do sortowania. Dostępne wartości:
- +created_at: Sortuj według czasu utworzenia w porządku rosnącym.
- -created_at: Sortuj według czasu utworzenia w porządku malejącym.

Zwraca

Zwraca stronicowaną listę Obiektów zadań 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

Streamuj 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 dla zadania Obraz na obraz do przesyłania strumieniowego.

Zwraca

Zwraca strumień Obiektów Zadania Obraz na obraz jako Server-Sent Events.

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

Obiekt zadania Obraz na obraz

Obiekt zadania Obraz na obraz to jednostka pracy, którą Meshy śledzi, aby wygenerować obraz z obrazów referencyjnych i wejściowego promptu tekstowego. Obiekt ma następujące właściwości:

Właściwości

Name
id
Type
string
Description
Unikalny identyfikator dla zadania. Chociaż używamy UUID sortowalnego k dla identyfikatorów zadań jako szczegółu implementacyjnego, nie powinieneś robić żadnych założeń dotyczących formatu id.
Name
type
Type
string
Description
Typ zadania generowania obrazu. Dla zadań Obraz na obraz, będzie to zawsze image-to-image.
Name
ai_model
Type
string
Description
Model AI używany do tego zadania. Możliwe wartości to nano-banana, nano-banana-2, nano-banana-pro lub gpt-image-2.
Name
prompt
Type
string
Description
Tekstowy prompt, który został użyty do kierowania transformacją obrazu.
Name
status
Type
string
Description
Status zadania. Możliwe wartości to PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Postęp zadania. Jeśli zadanie jeszcze się nie rozpoczęło, ta właściwość będzie miała wartość 0. Gdy zadanie zakończy się sukcesem, stanie się 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 12:00:00 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 jeszcze się nie rozpoczęło, 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 jeszcze się nie zakończyło, 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 pobieralnych URL do wygenerowanych obrazów. Gdy generate_multi_view jest włączone, ta tablica zawiera trzy URL obrazów reprezentujących różne kąty widzenia. W przeciwnym razie zawiera pojedynczy URL obrazu.
Name
task_error
Type
object
Description
Szczegóły błędu dla nieudanych zadań. Zobacz Błędy dla pełnej referencji obiektu task_error.
Name
consumed_credits
Type
integer
Description
Liczba kredytów zużytych przez to zadanie. Obecne, 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
}