Tekst na obraz API

Tekst na obraz API to funkcja, która pozwala zintegrować możliwości generowania obrazów AI od Meshy z własną aplikacją. Generuj wysokiej jakości obrazy na podstawie tekstowych podpowiedzi, korzystając z naszych zaawansowanych modeli AI.

POST/openapi/v1/text-to-image

Create a Text to Image Task

Ten punkt końcowy pozwala utworzyć nowe zadanie 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.

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, silniejszy 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 obrazu o wysokiej wierności (9 kredytów za obraz)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), model obrazu o wysokiej wierności (9 kredytów za obraz)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), model obrazu o wysokiej wierności (9 kredytów za obraz)
Name
prompt
Type
string
Wymagane
Description
Tekstowy opis obrazu, który chcesz wygenerować. Im bardziej szczegółowy opis, tym lepsze rezultaty.
Name
generate_multi_view
Type
boolean
domyślne false
Description
Gdy ustawione na true, generuje obraz Wiele widoków pokazujący obiekt 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śla tryb pozy dla generowania postaci. Jeśli pominięty, obraz jest generowany bez żadnych predefiniowanych póz.
Dostępne wartości: a-pose, t-pose
Name
aspect_ratio
Type
string
domyślne 1:1
Description
Określa proporcje generowanego obrazu. 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: 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 PNG w formacie RGBA z usuniętym tłem, dzięki czemu możesz umieścić obiekt na dowolnym tle.

Zwracane dane

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

Tryby niepowodzeń

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
Niewystarczające kredyty do wykonania tego zadania.
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 do pobrania.

Zwraca

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, w tym wszystkie powiązane obrazy i dane. Ta operacja jest nieodwracalna.

Parametry ścieżki

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

Status zadania

Zadanie, które nadal ma status PENDING, jest usuwane, a kredyty zużyte w momencie jego utworzenia są zwracane.

Zadanie, które ma już status IN_PROGRESS, nie może zostać usunięte: żądanie zostaje odrzucone z kodem 409 Conflict, a zadanie nadal działa. Kredyty za zadanie, które worker już rozpoczął, nie podlegają zwrotowi, więc usunięcie go w trakcie wykonywania kosztowałoby 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/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 pozwala pobrać listę zadań Tekst 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: Sortowanie według czasu utworzenia rosnąco.
- -created_at: Sortowanie według czasu utworzenia malejąco.

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łaj strumieniowo zadanie Tekst na obraz

Ten punkt końcowy przesyła strumieniowo aktualizacje w czasie rzeczywistym dla zadania Tekst na obraz za pomocą Server-Sent Events (SSE).

Parametry

Name
id
Type
path
Description
Unikalny identyfikator zadania Tekst na obraz, które ma być przesyłane strumieniowo.

Zwraca

Zwraca strumień Obiektów zadania Tekst na obraz w postaci 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 w celu wygenerowania obrazu na podstawie 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 k-sortable UUID, nie należy przyjmować żadnych założeń dotyczących formatu id.
Name
type
Type
string
Description
Typ zadania generowania obrazu. W przypadku 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-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ść wynosi 0. Gdy zadanie zakończy się sukcesem, przyjmie wartość 100.
Name
created_at
Type
timestamp
Description
Znacznik czasu utworzenia zadania, w milisekundach.
Znacznik czasu reprezentuje liczbę milisekund, jaka 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 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ść wynosi 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ść wynosi 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 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 znajduje się 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. Dla zadań ze statusem FAILED zwraca 0 (kredyty są zwracane w przypadku niepowodzenia).

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
}