Text to Image API

Generuj obrazy na podstawie promptu tekstowego za pomocą modeli AI firmy Meshy.

Tekst na obraz tworzy obrazy. Aby stworzyć model 3D na podstawie obiektu z obrazu, użyj Obraz na 3D. Aby stworzyć obiekt, który możesz trzymać w ręku lub wydrukować na podstawie zdjęcia, użyj Creative Lab API. Tworzą one obraz prototypowy, a następnie na jego podstawie budują model 3D, na przykład brelok, magnes na lodówkę, figurkę, lampę lub nakładkę na klawisz.

POST/openapi/v1/text-to-image

Utwórz zadanie Tekst na obraz

Tworzy zadanie Tekst na obraz. Zadanie wykonywane jest w tle. Informacje o tym, ile zwykle trwa zadanie, znajdziesz w sekcji Czasy przetwarzania.

Request

POST

/openapi/v1/text-to-image

# Generate an image from a text prompt
curl https://api.meshy.ai/openapi/v1/text-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "A majestic dragon soaring through clouds at sunset",
    "aspect_ratio": "16:9"
  }'

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. Informacje o cenach znajdziesz w sekcji Cennik.
Dostępne wartości:
- nano-banana: model standardowy
- nano-banana-2: bardziej wydajny niż nano-banana
- nano-banana-2-lite: uproszczona 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. W przypadku niższego planu 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 obraz do wygenerowania. Szczegółowy opis daje lepsze wyniki.
Name
generate_multi_view
Type
boolean
domyślne false
Description
Określa, czy generować obraz wielowidokowy przedstawiający obiekt z kilku kątów. Gdy wartość to true, nie można wysyłać aspect_ratio. Wysłanie obu zwraca 400.
Name
pose_mode
Type
string
Description
Poza postaci, a-pose lub t-pose. Pomiń, jeśli nie chcesz pozy.
Działanie pozy zależy od ai_model:
- nano-banana-2, nano-banana-2-lite i nano-banana-2-1: Meshy zachowuje wybrany przez Ciebie model. Obraz ma zawsze proporcje 3:4, a Meshy ignoruje aspect_ratio.
- nano-banana i nano-banana-pro: Meshy generuje obraz za pomocą nano-banana-pro, więc ai_model zadania jest odczytywany jako nano-banana-pro. Wymaga to planu Pro lub wyższego. Obraz ma zawsze proporcje 3:4, a Meshy ignoruje aspect_ratio.
- Modele GPT Image (gpt-image-2, gpt-image-2-5-flare i gpt-image-2-5-sunburst): Meshy zachowuje wybrany przez Ciebie model oraz Twoje aspect_ratio.
Name
aspect_ratio
Type
string
domyślne 1:1
Description
Kształt obrazu. Wartości, które można wysłać, zależą od ai_model.
Dostępne wartości:
- 1:1: kwadrat
- 16:9: szeroki format poziomy
- 9:16: szeroki format pionowy
- 4:3: standardowy format poziomy
- 3:4: standardowy format pionowy
- 3:2: format poziomy, tylko dla modeli GPT Image
- 2:3: format pionowy, tylko dla modeli GPT Image
Modele nano-banana (nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-2-1 i nano-banana-pro) zwracają 400 dla wartości 3:2 i 2:3.
Name
remove_background
Type
boolean
domyślne false
Description
Określa, czy usunąć tło obrazu. true zwraca przezroczysty plik PNG RGBA, dzięki czemu można umieścić obiekt na dowolnym tle.

Zwracane dane

Pole result odpowiedzi zawiera identyfikator nowego zadania Tekst na obraz.

Tryby niepowodzenia

Name
400 - Bad Request
Description
Żądanie nie może zostać wykonane. Komunikat o błędzie wskazuje znaleziony problem. Na przykład:
- Brakujący parametr: brakuje wymaganego parametru, takiego jak ai_model lub prompt.
- Nieprawidłowy parametr: ai_model lub aspect_ratio nie ma jednej z dozwolonych wartości.
- Konflikt: aspect_ratio zostało wysłane razem z generate_multi_view: true.
Popraw żądanie, a następnie wyślij je ponownie. Zobacz Błędy.
Name
401 - Unauthorized
Description
Brak klucza API lub klucz API jest nieprawidłowy. 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. Uaktualnij 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 (Insufficient funds) lub konto osiągnęło limit kredytów.
- Wymagany plan: żądanie korzysta z nano-banana-pro lub z pose_mode z nano-banana w ramach planu niższego niż Pro (Only Pro and above users can use nano-banana-pro lub Only Pro and above users can use A/T pose feature (requires nano-banana-pro)).
Sprawdź saldo kredytów oraz plan, a następnie spróbuj ponownie.
Name
429 - Too Many Requests
Description
Przekroczono limit szybkości. Odczekaj, a następnie spróbuj ponownie. Zobacz Limity szybkości.

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

Pobierz zadanie Tekst na obraz

Zwraca zadanie Tekst na obraz na podstawie jego ID.

Request

GET

/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "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 tworzenia.

Zwraca

Obiekt zadania Tekst na obraz.

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

Delete a Text to Image task

Trwale usuwa zadanie Tekst na obraz, wraz z jego obrazami i danymi. Nie można cofnąć usunięcia.

Request

DELETE

/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/text-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 w statusie PENDING zwraca kredyty wykorzystane przy jego utworzeniu.

Zadania w 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 usunięcie go 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 w statusie końcowym (SUCCEEDED, FAILED lub CANCELED) nie zwraca jego kredytów.

Zwraca

200 OK, gdy zadanie zostanie usunięte, lub 409 Conflict, gdy zadanie ma status IN_PROGRESS.

GET/openapi/v1/text-to-image

Lista zadań Tekst na obraz

Zwraca listę Twoich zadań Tekst na obraz oraz Obraz na obraz. Pole type każdego zadania określa, o który z dwóch rodzajów chodzi.

Request

GET

/openapi/v1/text-to-image

curl https://api.meshy.ai/openapi/v1/text-to-image?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-image",
    "ai_model": "nano-banana",
    "prompt": "A majestic dragon soaring through clouds at sunset",
    "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, które jest też wartością domyślną.
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

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

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

Strumieniowanie zadania Tekst na obraz

Strumieniuje aktualizacje zadania Tekst na obraz jako Server-Sent Events (SSE).

Request

GET

/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/text-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": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "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 Tekst na obraz jako Server-Sent Events.

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

Obiekt zadania Tekst na obraz

Obiekt zadania Tekst na obraz opisuje jedno generowanie obrazu na podstawie promptu tekstowego. Zawiera status, postęp oraz adresy URL obrazów, gdy zadanie zakończy się powodzeniem.

Właściwości

Example Text to Image Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "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 text-to-image.
Name
ai_model
Type
string
Description
Model AI użyty w zadaniu.
Możliwe 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, z którym utworzono zadanie.
Name
status
Type
string
Description
Status zadania, jeden z PENDING, IN_PROGRESS, SUCCEEDED, FAILED lub CANCELED.
Name
progress
Type
integer
Description
Ile zadania zostało wykonane, w procentach. Wynosi 0, dopóki zadanie się nie rozpocznie, i 100, gdy zakończy się powodzeniem.
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ę w kolejce przed tym zadaniem. 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 tablica zawiera jeden adres URL na widok, zwykle trzy. Jeśli Meshy nie jest w stanie oddzielić każdego widoku, zwraca ich mniej, a zadanie i tak kończy się powodzeniem. W przeciwnym razie zawiera jeden adres URL.
Name
task_error
Type
object
Description
Szczegóły błędu, gdy zadanie zakończy się niepowodzeniem. Wartość to null, chyba że status to FAILED. Zobacz Błędy.
Name
consumed_credits
Type
integer
Description
Liczba kredytów zużytych przez zadanie. Obecna, gdy status to PENDING, IN_PROGRESS lub SUCCEEDED. Wynosi 0 dla zadania ze statusem FAILED, ponieważ Meshy zwraca kredyty, gdy zadanie kończy się niepowodzeniem.