API Текст у зображення

API Текст у зображення — це функція, яка дозволяє інтегрувати можливості генерації зображень за допомогою штучного інтелекту Meshy у ваш власний додаток. Генеруйте високоякісні зображення з текстових підказок, використовуючи наші потужні моделі штучного інтелекту.

POST/openapi/v1/text-to-image

Створення завдання Текст у зображення

Цей endpoint дозволяє створити нове завдання Текст у зображення. Зверніться до Об'єкт завдання Текст у зображення, щоб дізнатися, які властивості включені в об'єкт завдання Текст у зображення.

Параметри

Name
ai_model
Type
string
Обов'язковий
Description
Ідентифікатор моделі для генерації зображення.
Доступні значення:
- nano-banana: Стандартна модель (3 кредити за зображення)
- nano-banana-2: Збалансована модель з більшою потужністю, ніж стандартна (6 кредитів за зображення)
- nano-banana-pro: Про модель з покращеною якістю (9 кредитів за зображення)
- gpt-image-2: OpenAI GPT Image 2, високоякісна модель зображення (9 кредитів за зображення)
Name
prompt
Type
string
Обов'язковий
Description
Текстовий опис зображення, яке ви хочете згенерувати. Будьте описовими для найкращих результатів.
Name
generate_multi_view
Type
boolean
за замовчуванням false
Description
Якщо встановлено значення true, генерує мультивидове зображення, яке показує об'єкт з різних кутів.
Коли generate_multi_view встановлено в true, параметр aspect_ratio не може бути встановлений.
Name
pose_mode
Type
string
Description
Вкажіть режим пози для генерації персонажа. Якщо не вказано, зображення генерується без попередньо встановлених поз.
Доступні значення: a-pose, t-pose
Name
aspect_ratio
Type
string
за замовчуванням 1:1
Description
Вкажіть співвідношення сторін згенерованого зображення. Дозволені значення залежать від вибраної 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
Доступні значення:
- 1:1: Квадратний формат
- 16:9: Широкоформатний ландшафт
- 9:16: Широкоформатний портрет
- 4:3: Стандартний ландшафт (не підтримується gpt-image-2)
- 3:4: Стандартний портрет (не підтримується gpt-image-2)
- 3:2: Ландшафт (підтримується лише gpt-image-2)
- 2:3: Портрет (підтримується лише gpt-image-2)
Name
remove_background
Type
boolean
за замовчуванням false
Description
Якщо встановлено значення true, згенероване зображення повертається у вигляді прозорого RGBA PNG з видаленим фоном, щоб ви могли накласти об'єкт на будь-який фон.

Повертає

Властивість result відповіді містить id завдання новоствореного завдання Текст у зображення.

Режими відмови

Name
400 - Bad Request
Description
Запит був неприйнятним. Поширені причини:
- Відсутній параметр: Відсутній обов'язковий параметр (наприклад, ai_model, prompt).
- Неправильний параметр: ai_model або aspect_ratio не є одним з дозволених значень.
- Конфлікт: generate_multi_view і aspect_ratio не можуть використовуватися одночасно.
Name
401 - Unauthorized
Description
Автентифікація не вдалася. Будь ласка, перевірте ваш API key.
Name
402 - Payment Required
Description
Недостатньо кредитів для виконання цього завдання.
Name
429 - Too Many Requests
Description
Ви перевищили своє обмеження частоти.

Запит

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

Відповідь

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

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

Отримання завдання Текст у зображення

Цей endpoint дозволяє отримати завдання Текст у зображення, маючи дійсний id завдання. Зверніться до Об'єкт завдання Текст у зображення, щоб дізнатися, які властивості включені в об'єкт завдання Текст у зображення.

Параметри

Name
id
Type
path
Description
Унікальний ідентифікатор для завдання Текст у зображення, яке потрібно отримати.

Повертає

Відповідь містить об'єкт завдання Текст у зображення. Перевірте розділ Об'єкт завдання Текст у зображення для деталей.

Запит

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

Відповідь

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

Видалити завдання Текст у зображення

Цей endpoint назавжди видаляє завдання Текст у зображення, включаючи всі пов'язані зображення та дані. Ця дія є незворотною.

Параметри шляху

Name
id
Type
path
Description
Ідентифікатор завдання Текст у зображення, яке потрібно видалити.

Повертає

Повертає 200 OK у разі успіху.

Запит

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

Відповідь

// Returns 200 Ok on success.

GET/openapi/v1/text-to-image

Список завдань Текст у зображення

Цей endpoint дозволяє отримати список завдань Текст у зображення.

Параметри

Name
page_num
Type
integer
Description
Номер сторінки для пагінації. Починається і за замовчуванням дорівнює 1.
Name
page_size
Type
integer
Description
Ліміт розміру сторінки. За замовчуванням 10 елементів. Максимально дозволено 50 елементів.
Name
sort_by
Type
string
Description
Поле для сортування. Доступні значення:
- +created_at: Сортувати за часом створення у зростаючому порядку.
- -created_at: Сортувати за часом створення у спадному порядку.

Повертає

Повертає список з пагінацією Об'єктів завдань Текст у зображення.

Запит

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

Відповідь

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

Потокове передавання завдання "Текст у зображення"

Ця кінцева точка передає оновлення в реальному часі для завдання "Текст у зображення" за допомогою Server-Sent Events (SSE).

Параметри

Name
id
Type
path
Description
Унікальний ідентифікатор для завдання "Текст у зображення", яке потрібно передати.

Повертає

Повертає потік Об'єктів завдання "Текст у зображення" як Server-Sent Events.

Для завдань зі статусом PENDING або IN_PROGRESS потік відповіді міститиме лише необхідні поля progress та status.

Запит

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

Потік відповіді

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

Об'єкт завдання "Текст у зображення"

Об'єкт завдання "Текст у зображення" є робочою одиницею, яку Meshy відстежує для створення зображення з введення текстового prompt. Об'єкт має наступні властивості:

Властивості

Name
id
Type
string
Description
Унікальний ідентифікатор для завдання. Хоча ми використовуємо k-сортований UUID для ідентифікаторів завдань як деталь реалізації, ви не повинні робити жодних припущень щодо формату id.
Name
type
Type
string
Description
Тип завдання генерації зображення. Для завдань "Текст у зображення" це завжди буде text-to-image.
Name
ai_model
Type
string
Description
AI модель, використана для цього завдання. Можливі значення: nano-banana, nano-banana-2, nano-banana-pro або gpt-image-2.
Name
prompt
Type
string
Description
Текстовий prompt, який був використаний для створення зображення.
Name
status
Type
string
Description
Статус завдання. Можливі значення: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Прогрес завдання. Якщо завдання ще не розпочато, ця властивість буде 0. Після успішного завершення завдання це значення стане 100.
Name
created_at
Type
timestamp
Description
Мітка часу створення завдання, у мілісекундах.
Мітка часу представляє кількість мілісекунд, що минули з 1 січня 1970 року UTC, відповідно до стандарту RFC 3339. Наприклад, п'ятниця, 1 вересня 2023 року, 12:00:00 GMT представлена як 1693569600000. Це стосується всіх міток часу в Meshy API.
Name
started_at
Type
timestamp
Description
Мітка часу початку завдання, у мілісекундах. Якщо завдання ще не розпочато, ця властивість буде 0.
Name
finished_at
Type
timestamp
Description
Мітка часу завершення завдання, у мілісекундах. Якщо завдання ще не завершено, ця властивість буде 0.
Name
expires_at
Type
timestamp
Description
Мітка часу, коли результат завдання закінчується, у мілісекундах.
Name
preceding_tasks
Type
integer
Description
Кількість попередніх завдань.
Значення цього поля має сенс лише якщо статус завдання PENDING.
Name
image_urls
Type
array
Description
Масив завантажуваних URL-адрес до створених зображень. Коли generate_multi_view увімкнено, цей масив містить три URL-адреси зображень, що представляють різні кути огляду. В іншому випадку він містить одну URL-адресу зображення.
Name
task_error
Type
object
Description
Деталі помилки для невдалих завдань. Дивіться Помилки для повної довідки по об'єкту task_error.
Name
consumed_credits
Type
integer
Description
Кількість кредитів, спожитих цим завданням. Присутній, коли статус завдання PENDING, IN_PROGRESS або SUCCEEDED. Повертає 0 для завдань FAILED (кредити повертаються у разі невдачі).

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
}