API Obraz na obraz

API Obraz na obraz to funkcja, która pozwala zintegrować 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 i promptów tekstowych z naszymi zaawansowanymi modelami AI.

POST/openapi/v1/image-to-image

Utwórz zadanie Obraz na obraz

Ten punkt końcowy pozwala utworzyć nowe zadanie Obraz na obraz. Zapoznaj się z Obiektem 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: 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 z ulepszoną jakością (9 kredytów za obraz)
    • gpt-image-2: OpenAI GPT Image 2, model edycji obrazów 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 podania każdego obrazu:

    • Publicznie dostępny URL: URL dostępny z publicznego internetu.
    • Data URI: Data URI obrazu zakodowany w base64. Przykład Data URI: data:image/jpeg;base64,<your base64-encoded image data>.
  • Name
    generate_multi_view
    Type
    boolean
    domyślne false
    Description

    Po ustawieniu na true generuje obraz typu Wiele widoków, pokazujący obiekt z wielu kątów.

Zwraca

Właściwość result odpowiedzi zawiera id zadania 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: Nie udało się pobrać jednego lub więcej reference_image_urls.
  • 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
    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}"
    ]
  }'

Response

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

Pobierz zadanie Obraz na obraz

Ten punkt końcowy umożliwia pobranie zadania Obraz na obraz przy użyciu prawidłowego id zadania. Zobacz Obiekt zadania Obraz na obraz, aby sprawdzić, które 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.

Zwraca

Odpowiedź zawiera obiekt zadania Obraz na obraz. Sprawdź sekcję Obiekt zadania Obraz na obraz, aby uzyskać szczegóły.

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

Usuń zadanie Obraz na obraz

Ten punkt końcowy trwale usuwa zadanie Obraz na obraz, w tym wszystkie powiązane obrazy i dane. Tej czynności nie można cofnąć.

Parametry ścieżki

  • Name
    id
    Type
    path
    Description

    Identyfikator zadania Obraz na obraz do usunięcia.

Zwraca

Zwraca 200 OK w przypadku powodzenia.

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 umożliwia pobranie listy zadań Obraz na obraz.

Parametry

  • Name
    page_num
    Type
    integer
    Description

    Numer strony dla stronicowania. Zaczyna się od 1 i domyślnie wynosi 1.

  • Name
    page_size
    Type
    integer
    Description

    Limit rozmiaru strony. Domyślnie 10 elementów. Maksymalnie dozwolone to 50 elementów.

  • Name
    sort_by
    Type
    string
    Description

    Pole, według którego sortować. 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

Strumieniuj zadanie Obraz na obraz

Ten punkt końcowy strumieniuje 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 strumieniowania.

Zwraca

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

W przypadku 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 na podstawie danych wejściowych: obrazów referencyjnych i 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 k-sortowalnego UUID dla identyfikatorów zadań, nie należy przyjmować żadnych założeń dotyczących formatu identyfikatora.

  • Name
    type
    Type
    string
    Description

    Typ zadania generowania obrazu. W przypadku zadań Obraz na obraz będzie to zawsze image-to-image.

  • Name
    ai_model
    Type
    string
    Description

    Model AI użyty dla 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 jedna z PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    progress zadania. Jeśli zadanie nie zostało jeszcze rozpoczęte, ta właściwość będzie mieć wartość 0. Gdy zadanie zakończy się sukcesem, wartość ta 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 r. UTC, zgodnie ze standardem RFC 3339. Na przykład piątek, 1 września 2023 12:00:00 PM 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 mieć 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 mieć 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 możliwych do pobrania adresów URL do wygenerowanych obrazów. Gdy generate_multi_view jest włączone, ta tablica zawiera trzy adresy URL obrazów przedstawiają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ń. Zobacz Błędy, aby uzyskać pełną referencję 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
}