API Tekst na obraz

API Tekst na obraz 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 promptów tekstowych, korzystając z naszych zaawansowanych modeli AI.

POST/openapi/v1/text-to-image

Utwórz zadanie Tekst na obraz

Ten punkt końcowy pozwala utworzyć nowe zadanie Tekst na obraz. Zobacz Obiekt zadania Tekst na obraz, aby sprawdzić, które właściwości są zawarte w obiekcie zadania Tekst na obraz.

Parametry

  • Name
    ai_model
    Type
    string
    Wymagane
    Description

    Identyfikator modelu do użycia przy generowaniu 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-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 z ograniczoną obsługą proporcji obrazu (9 kredytów za obraz)
  • Name
    prompt
    Type
    string
    Wymagane
    Description

    Tekstowy opis obrazu, który chcesz wygenerować. Aby uzyskać najlepsze wyniki, podaj opis szczegółowo.

  • Name
    generate_multi_view
    Type
    boolean
    domyślne false
    Description

    Gdy ustawiono na true, generuje obraz z wieloma widokami pokazujący obiekt z wielu kątów.

    Gdy generate_multi_view ma wartość true, parametr aspect_ratio nie może być ustawiony.

  • Name
    pose_mode
    Type
    string
    Description

    Określ pose_mode dla generowania postaci. Jeśli pominięto, obraz jest generowany bez żadnych presetów pozy.

    Dostępne wartości: a-pose, t-pose

  • 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-pro: 1:1, 16:9, 9:16, 4:3, 3:4
    • gpt-image-2: tylko 1:1, 3:2, 2:3

    Dostępne wartości:

    • 1:1: Format kwadratowy
    • 16:9: Szeroki format poziomy (nieobsługiwany przez gpt-image-2)
    • 9:16: Szeroki format pionowy (nieobsługiwany przez gpt-image-2)
    • 4:3: Standardowy format poziomy (nieobsługiwany przez gpt-image-2)
    • 3:4: Standardowy format pionowy (nieobsługiwany przez gpt-image-2)
    • 3:2: Format poziomy (obsługiwany tylko przez gpt-image-2)
    • 2:3: Format pionowy (obsługiwany tylko przez gpt-image-2)

Zwraca

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

Tryby niepowodzenia

  • 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ę. 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/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 przy użyciu prawidłowego id zadania. Zobacz Obiekt zadania Tekst na obraz, aby sprawdzić, które właściwości są zawarte w obiekcie 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. Tej akcji nie można cofnąć.

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 pobrać listę zadań Tekst na obraz.

Parametry

  • Name
    page_num
    Type
    integer
    Description

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

  • Name
    page_size
    Type
    integer
    Description

    Limit rozmiaru strony. Domyślnie 10 elementów. Maksymalna dozwolona wartość to 50 elementów.

  • Name
    sort_by
    Type
    string
    Description

    Pole do sortowania. 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 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

Strumieniuj zadanie Tekst na obraz

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

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 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:

Properties

  • Name
    id
    Type
    string
    Description

    Unikalny identyfikator zadania. Chociaż używamy k-sortable UUID dla identyfikatorów zadań jako szczegółu implementacyjnego, nie należy przyjmować żadnych założeń dotyczących formatu id.

  • Name
    type
    Type
    string
    Description

    Typ zadania generowania obrazu. Dla zadań Tekst na obraz będzie to zawsze text-to-image.

  • Name
    ai_model
    Type
    string
    Description

    Model AI użyty w tym zadaniu. 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 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. Po pomyślnym zakończeniu zadania 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 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 adresów URL do pobrania wygenerowanych obrazów. Gdy generate_multi_view jest włączone, ta tablica zawiera trzy adresy URL obrazów reprezentują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 zadań zakończonych niepowodzeniem. Zobacz Błędy, aby uzyskać pełne odniesienie do 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 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
}