Tekst na obraz API

Tekst na obraz API to funkcja, która pozwala zintegrować możliwości generowania obrazów AI Meshy z własną aplikacją. Generuj wysokiej jakości obrazy na podstawie podpowiedzi tekstowych, korzystając z naszych zaawansowanych modeli 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ę, figurka, lampa lub nakładka na klawisz na podstawie zdjęcia — użyj Creative Lab APIs (obraz prototypu → budowa modelu 3D). Jeśli celem jest model 3D tego, co znajduje się na zdjęciu, użyj Obraz na 3D.

POST/openapi/v1/text-to-image

Utwórz zadanie Tekst na obraz

Ten punkt końcowy umożliwia utworzenie nowego zadania Tekst na obraz. Zapoznaj się z Obiektem zadania Tekst na obraz, aby zobaczyć, jakie właściwości są zawarte w obiekcie zadania Tekst na obraz.

Zadanie działa w tle. Informacje o tym, ile zwykle to trwa, znajdziesz w sekcji Czasy przetwarzania.

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 zbalansowany o większych możliwościach niż standardowy (6 kredytów za obraz)
- nano-banana-2-lite: lekki wariant 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, model obrazów o wysokiej wierności (9 kredytów za obraz)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), model obrazów o wysokiej wierności (9 kredytów za obraz)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), model obrazów o wysokiej wierności (9 kredytów za obraz)
Name
prompt
Type
string
Wymagane
Description
Tekstowy opis obrazu, który chcesz wygenerować. Im bardziej opisowy prompt, tym lepsze wyniki.
Name
generate_multi_view
Type
boolean
domyślne false
Description
Gdy ustawione na true, generuje obraz w trybie Wiele widoków, pokazujący podmiot z wielu kątów.
Gdy generate_multi_view ma wartość true, parametru aspect_ratio nie można ustawić.
Name
pose_mode
Type
string
Description
Określ tryb pozy dla generowania postaci. Gdy parametr jest pominięty, obraz jest generowany bez żadnych predefiniowanych póz.
Dostępne wartości: a-pose, t-pose
W przypadku nano-banana, nano-banana-2, nano-banana-2-lite i nano-banana-pro ustawienie pose_mode ustala proporcje wyjściowego obrazu na 3:4, a każda wysłana wartość aspect_ratio jest ignorowana. nano-banana-2 i nano-banana-2-lite zachowują żądany model. W przypadku nano-banana lub nano-banana-pro obraz z pozą jest generowany przez nano-banana-pro (wartość ai_model zadania jest odczytywana jako nano-banana-pro), co wymaga planu Pro lub wyższego. Modele GPT Image (gpt-image-2, gpt-image-2-5-flare, gpt-image-2-5-sunburst) zachowują żądany model oraz aspect_ratio.
Name
aspect_ratio
Type
string
domyślne 1:1
Description
Określ proporcje wygenerowanego obrazu. 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: format panoramiczny poziomy
- 9:16: format panoramiczny pionowy
- 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, wygenerowany obraz jest zwracany jako przezroczysty plik PNG RGBA z usuniętym tłem, dzięki czemu możesz umieścić podmiot na dowolnym tle.

Zwracane dane

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

Tryby niepowodzenia

Name
400 - Bad Request
Description
Żądanie było niepoprawne. Typowe przyczyny:
- Brakujący parametr: brakuje wymaganego parametru (np. ai_model, prompt).
- Nieprawidłowy parametr: ai_model lub aspect_ratio nie jest jedną z dozwolonych wartości.
- 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
Typowe przyczyny:
- Niewystarczające kredyty: Twoje konto nie ma wystarczającej liczby kredytów, aby wykonać to zadanie (Insufficient funds).
- Wymagany plan: nano-banana-pro lub pose_mode z nano-banana wymaga planu Pro lub wyższego (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)).
Name
429 - Too Many Requests
Description
Przekroczono limit szybkości.

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

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

Pobierz zadanie Tekst na obraz

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

Parametry

Name
id
Type
path
Description
Unikalny identyfikator zadania Tekst na obraz, które ma zostać pobrane.

Wartość zwracana

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

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

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

Usuń zadanie Tekst na obraz

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

Parametry ścieżki

Name
id
Type
path
Description
ID zadania Tekst na obraz, które ma zostać usunięte.

Status zadania

Zadanie, które wciąż ma status PENDING, zostaje usunięte, a kredyty pobrane w momencie utworzenia są zwracane.

Zadania, które jest już w stanie IN_PROGRESS, nie można usunąć: żądanie zostaje odrzucone 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) zostaje usunięte bez zwrotu kredytów.

Zwraca

Zwraca 200 OK w przypadku powodzenia lub 409 Conflict, gdy zadanie ma status IN_PROGRESS.

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 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/text-to-image

Lista zadań Tekst na obraz

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

Parametry

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

Zwraca

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

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

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

Przesyłanie strumieniowe zadania Tekst na obraz

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

Parametry

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

Zwraca

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

W przypadku zadań o statusie PENDING lub IN_PROGRESS strumień odpowiedzi będzie zawierał tylko niezbędne pola progress i status.

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.
// 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": "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=***"
  ]
}

Obiekt zadania Tekst na obraz

Obiekt zadania Tekst na obraz to jednostka pracy, którą Meshy śledzi, aby wygenerować obraz na podstawie wejściowego 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 formie UUID z sortowaniem 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ń Tekst na obraz zawsze będzie to text-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 wygenerowania 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 jeszcze się nie rozpoczęło, ta właściwość będzie miała wartość 0. Gdy zadanie zakończy się powodzeniem, przyjmie wartość 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 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 zadań poprzedzających.
Wartość tego pola ma znaczenie tylko wtedy, gdy status zadania to PENDING.
Name
image_urls
Type
array
Description
Tablica adresów URL umożliwiających pobranie wygenerowanych obrazów. Gdy włączona jest opcja generate_multi_view, tablica ta zawiera trzy adresy URL obrazów przedstawiających 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. Obecna, gdy status zadania to PENDING, IN_PROGRESS lub SUCCEEDED. Zwraca 0 dla zadań FAILED (w przypadku niepowodzenia kredyty są zwracane).

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