API Зображення у зображення

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

POST/openapi/v1/image-to-image

Створити завдання Зображення у зображення

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

Параметри

Name
ai_model
Type
string
Обов'язковий
Description
ID моделі, яку потрібно використовувати для генерації зображення.
Доступні значення:
- nano-banana: Стандартна модель (3 кредити за зображення)
- nano-banana-2: Збалансована модель із потужнішими можливостями, ніж стандартна (6 кредитів за зображення)
- nano-banana-pro: Pro-модель із підвищеною якістю (9 кредитів за зображення)
- gpt-image-2: OpenAI GPT Image 2, модель редагування зображень високої точності (12 кредитів за зображення)
Name
prompt
Type
string
Обов'язковий
Description
Текстовий опис трансформації або редагування, яке ви хочете застосувати до референсних зображень.
Name
reference_image_urls
Type
array
Обов'язковий
Description
Масив із 1–5 референсних зображень для використання в завданні редагування зображення. Наразі ми підтримуємо формати .jpg, .jpeg і .png.
Існує два способи надати кожне зображення:
- Загальнодоступний URL: URL, доступний із публічного інтернету.
- Data URI: Data URI зображення, закодований у base64. Приклад Data URI: data:image/jpeg;base64,<your base64-encoded image data>.
Name
generate_multi_view
Type
boolean
за замовчуванням false
Description
Якщо встановлено true, генерує зображення Мультивиду, що показує об’єкт з кількох ракурсів.

Повертає

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

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

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

Request

POST

/openapi/v1/image-to-image

# Transform a reference image with a text prompt
curl https://api.meshy.ai/openapi/v1/image-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "reference_image_urls": [
      "<your publicly accessible image url or base64-encoded data URI>"
    ]
  }'


 ## Using Data URI example
curl https://api.meshy.ai/openapi/v1/image-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "reference_image_urls": [
      "data:image/png;base64,${YOUR_BASE64_ENCODED_IMAGE_DATA}"
    ]
  }'

Response

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

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

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

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

Параметри

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

Повертає

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

Request

GET

/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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/image-to-image/:id

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

Ця кінцева точка назавжди видаляє завдання Зображення у зображення, включно з усіма пов’язаними зображеннями та даними. Ця дія є незворотною.

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

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

Повернення

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

Request

DELETE

/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.

GET/openapi/v1/image-to-image

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

Ця кінцева точка дозволяє отримати список завдань Зображення у зображення.

Параметри

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

Повертає

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

Request

GET

/openapi/v1/image-to-image

curl https://api.meshy.ai/openapi/v1/image-to-image?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "image-to-image",
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "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/image-to-image/:id/stream

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

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

Параметри

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

Повертає

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

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

Request

GET

/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/image-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": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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-sortable UUID, вам не слід робити жодних припущень щодо формату id.
Name
type
Type
string
Description
Тип завдання генерації зображення. Для завдань Зображення у зображення це завжди буде image-to-image.
Name
ai_model
Type
string
Description
Модель ШІ, використана для цього завдання. Можливі значення: 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
Значення progress для завдання. Якщо завдання ще не розпочато, ця властивість буде 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 Image to Image Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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
}