Tekst na obraz API

Tekst na obraz API to funkcja, która pozwala na integrację możliwości generowania obrazów AI Meshy z Twoją własną aplikacją. Generuj obrazy wysokiej jakości z tekstowych podpowiedzi, korzystając z naszych potężnych modeli AI.

POST/openapi/v1/text-to-image

Utwórz zadanie Tekst na obraz

Ten punkt końcowy pozwala na utworzenie nowego zadania Tekst na obraz. Odnieś się do Obiekt zadania Tekst na obraz, aby zobaczyć, które właściwości są zawarte w obiekcie zadania Tekst 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 obrazu o wysokiej wierności (9 kredytów za obraz)
Name
prompt
Type
string
Wymagane
Description
Opis tekstowy obrazu, który chcesz wygenerować. Bądź opisowy dla najlepszych wyników.
Name
generate_multi_view
Type
boolean
domyślne false
Description
Gdy ustawione na true, generuje obraz z wieloma widokami pokazującymi temat z różnych kątów.
Gdy generate_multi_view jest true, parametr aspect_ratio nie może być ustawiony.
Name
pose_mode
Type
string
Description
Określ tryb pozy dla generowania postaci. Gdy pominięty, obraz jest generowany bez żadnych ustawień pozy.
Dostępne wartości: a-pose, t-pose
Name
aspect_ratio
Type
string
domyślne 1:1
Description
Określ 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: 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, wygenerowany obraz jest zwracany jako przezroczysty RGBA PNG z usuniętym tłem, dzięki czemu możesz umieścić temat na dowolnym tle.

Zwraca

Właściwość result odpowiedzi zawiera id nowo utworzonego zadania Tekst 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).
- 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ę. 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/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 pozwala na pobranie zadania Tekst na obraz, podając prawidłowy id zadania. Odwołaj się do Obiekt zadania Tekst na obraz, aby zobaczyć, które właściwości są zawarte w obiekcie zadania Tekst na obraz.

Parametry

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

Zwraca

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

Żądanie

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

Odpowiedź

{
  "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 akcja jest nieodwracalna.

Parametry ścieżki

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

Zwraca

Zwraca 200 OK w przypadku powodzenia.

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

// Returns 200 Ok on success.

GET/openapi/v1/text-to-image

Lista zadań Tekst na obraz

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

Parametry

Name
page_num
Type
integer
Description
Numer strony dla stronicowania. Zaczyna się i domyślnie ustawia na 1.
Name
page_size
Type
integer
Description
Limit rozmiaru strony. Domyślnie 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ń 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

Streamowanie zadania Tekst na obraz

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

Parametry

Name
id
Type
path
Description
Unikalny identyfikator dla zadania Tekst na obraz do streamowania.

Zwraca

Zwraca strumień Obiektów zadania Tekst 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/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 jest jednostką pracy, którą Meshy śledzi, aby wygenerować obraz z 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ż używamy UUID sortowalnego według klucza dla identyfikatorów zadań jako szczegółu implementacji, nie powinieneś zakładać żadnego formatu 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ż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 wygenerowania 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, wartość ta wyniesie 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 roku 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-i do wygenerowanych obrazów. Gdy generate_multi_view jest włączone, ta tablica zawiera trzy URL-e 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).

Przykład obiektu zadania Tekst na obraz

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