Relief API

Перетворіть одну фотографію на 3D-модель у вигляді барельєфа та 16-бітну карту глибини для 3D-друку, лазерного гравіювання та ЧПУ-різьблення.

POST/openapi/v1/relief

Створення завдання Relief

Створює завдання Relief. Це завдання перетворює фотографію на модель барельєфа. У разі успіху завдання створює модель у вигляді файлу GLB та файлу STL, 16-бітну карту глибини в градаціях сірого та зображення попереднього перегляду. Щоб отримати лише карту глибини, встановіть should_generate_model на false.

Завдання виконується у фоновому режимі.

Завдання Relief не може бути вхідними даними для іншої кінцевої точки, наприклад Remesh, Convert або Auto Split. Такі запити повертають 403.

Request

POST

/openapi/v1/relief

# Simple request: a low relief, 60 mm on its longer side
curl https://api.meshy.ai/openapi/v1/relief \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

# Advanced request: a deep 120 mm relief with a thicker base, curved from side to side
curl https://api.meshy.ai/openapi/v1/relief \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "variant": "high",
    "size_mm": 120,
    "carving_depth_mm": 10,
    "base_thickness_mm": 3,
    "bend_mode": "convex",
    "bend_angle": 90
  }'

Response

{
  "result": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20"
}

Параметри

Name
image_url
Type
string
Обов'язковий
Description
Фотографія, яку потрібно перетворити на рельєф, у вигляді публічної URL-адреси або Data URI (data:image/png;base64,...).
Зображення має бути файлом JPG, JPEG, PNG або WebP розміром не більше 20 МБ та не менше 32 × 32 пікселів. Його довша сторона може бути не більше ніж приблизно у 16 разів довшою за коротшу. Будь-яке інше зображення повертає 400. Meshy заповнює прозорі області чорним кольором перед побудовою рельєфу.
Name
variant
Type
string
за замовчуванням low
Description
Стиль рельєфу. Він формує карту глибини та задає значення carving_depth_mm за замовчуванням.
Доступні значення:
- high: глибше різьблення, для деталей, надрукованих на 3D-принтері.
- low: неглибоке різьблення, для лазерного гравіювання, ЧПУ-різьблення та тонких табличок.
Надсилання null або "" рівнозначне пропуску цього параметра. Будь-яке інше значення повертає 400.
Name
should_generate_model
Type
boolean
за замовчуванням true
Description
Чи потрібно будувати модель рельєфу. Встановіть значення false для завдання, що створює лише карту глибини, без моделі та зображення попереднього перегляду. Meshy все одно перевіряє параметри розміру, різьблення, основи, вигину та роздільної здатності, але не використовує їх. Це не впливає на вартість у кредитах.

Name
size_mm
Type
number
за замовчуванням 60
Description
Довжина довшої сторони фотографії на моделі, виміряна у плоскому вигляді до будь-якого вигину, від 20 до 250 міліметрів. З параметром remove_base модель може бути меншою.
Name
carving_mode
Type
string
за замовчуванням emboss
Description
Чи виступає об'єкт над пластиною, чи вирізається в ній.
Доступні значення:
- emboss: ближчі частини фотографії виступають.
- engrave: глибина інвертується, тому ближчі частини вирізаються всередину.
Карта глибини однакова в обох режимах.
Name
carving_depth_mm
Type
number
за замовчуванням 6 (high), 3 (low)
Description
Наскільки глибоко вирізається рельєф, від 0 до 60 міліметрів. Якщо remove_base встановлено на true, значення 0 залишає порожню модель. Завдання все одно виконується успішно і коштує 20 кредитів, а його файли GLB і STL не містять геометрії.

Name
remove_base
Type
boolean
за замовчуванням false
Description
Чи потрібно відрізати фон і не будувати основу-пластину. Якщо значення true, параметр removal_threshold визначає, що вважається фоном. Meshy перевіряє removal_threshold у будь-якому випадку.

Застосовується лише коли remove_base = true

Name
removal_threshold
Type
number
за замовчуванням 0.01
Description
Глибина, нижче якої Meshy відрізає фон, від 0.01 до 1, де карта глибини проходить від 0 до 1. Високе значення може відрізати весь рельєф і залишити порожню модель, яка все одно успішно створюється і оплачується.

Name
base_thickness_mm
Type
number
за замовчуванням 1, or 0 with remove_base
Description
Товщина основи-пластини, від 0.1 до 10 міліметрів. Якщо remove_base має значення true, пропустіть цей параметр або надішліть 0.

Name
bend_mode
Type
string
за замовчуванням off
Description
Чи потрібно вигинати рельєф і в якому напрямку. Коли значення не off, параметри bend_axis та bend_angle формують вигин. Meshy перевіряє їх у будь-якому випадку.
Доступні значення:
- off: плаский рельєф.
- convex: передня частина випинається назовні.
- concave: передня частина вигинається всередину.

Застосовується лише коли bend_mode = convex or concave

Name
bend_axis
Type
string
за замовчуванням xz
Description
Які краї закручує вигин.
Доступні значення:
- xz: лівий і правий краї.
- yz: верхній і нижній краї.
Name
bend_angle
Type
number
за замовчуванням 60
Description
Дуга, яку охоплює вигин, від 0 до 360 градусів. Нижче 1 рельєф залишається плоским.

Name
mesh_resolution
Type
integer
за замовчуванням 1024
Description
Кількість точок сітки вздовж довшої сторони фотографії, від 512 до 2048. Вище значення зберігає детальнішу деталізацію та збільшує розмір файлів. За замовчуванням, при 1024, файл GLB має розмір приблизно 40–50 МБ, а файл STL — приблизно 80–105 МБ. Квадратна фотографія дає більші розміри. При 2048 вони становлять приблизно 150 МБ і 300 МБ. Вигин збільшує розміри: файл STL може досягати приблизно 800 МБ при 2048.

Результати

202 Accepted, з ідентифікатором нового завдання Relief у полі result.

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

Name
400 - Bad Request
Description
Запит не може бути виконаний. Повідомлення про помилку вказує, яку проблему було виявлено. Наприклад:
- Відсутній параметр: image_url не було надіслано.
- Недійсний параметр: Параметр має неправильний тип, виходить за межі діапазону або не входить до списку доступних значень. Наприклад, variant не дорівнює high або low, або mesh_resolution не є цілим числом від 512 до 2048.
- Товщина основи: base_thickness_mm не дорівнює 0 при remove_base зі значенням true, або менша за 0.1 без нього.
- Недоступна URL-адреса: Meshy не може завантажити зображення за image_url, наприклад тому що URL-адреса повертає 404 або час очікування вичерпано.
- Недійсне зображення: Зображення не є файлом JPG, JPEG, PNG або WebP, перевищує 20 МБ, менше за 32 × 32 пікселів, має занадто багато пікселів або не може бути прочитане.
- Екстремальне співвідношення сторін: Довша сторона зображення більш ніж приблизно у 16 разів довша за коротшу.
Виправте запит, потім надішліть його знову. Meshy не стягує плату за це. Див. Помилки.
Name
401 - Unauthorized
Description
API-ключ відсутній або недійсний. Перевірте заголовок Authorization.
Name
402 - Payment Required
Description
Наприклад:
- Недостатньо кредитів: На рахунку недостатньо кредитів для цього завдання, або рахунок досяг ліміту кредитів. Перевірте свій баланс кредитів, потім повторіть спробу.
- Безкоштовний план: Для створення завдання потрібен платний план. Оновіть свій план у налаштуваннях підписки, потім повторіть спробу.
Name
403 - Forbidden
Description
Модерація контенту заблокувала зображення. Meshy не стягує плату за цей запит. Надішліть інше зображення.
Name
429 - Too Many Requests
Description
Було досягнуто одне з таких обмежень:
- Ви надіслали забагато запитів. Зачекайте, потім повторіть спробу. Див. Обмеження частоти запитів.
- Забагато ваших завдань перебуває в черзі або виконується. Зачекайте, поки деякі з них завершаться, потім повторіть спробу.
- На безлімітному плані без залишку кредитів ви досягли кількості завдань, які можуть виконуватися без кредитів. Зачекайте завершення завдання або поповніть кредити.

Якщо перевірка безпеки відхиляє зображення під час виконання завдання, завдання завершується помилкою зі значенням task_error.type, встановленим на invalid_input, і task_error.code, встановленим на provider_content_refused. Meshy повертає кредити за завдання. Надішліть інше зображення. Див. Помилки.

GET/openapi/v1/relief/:id

Отримати завдання Рельєфу

Повертає завдання Рельєфу за його ID.

Request

GET

/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20

curl https://api.meshy.ai/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "type": "relief",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
  },
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000060000,
  "expires_at": 1700259260000,
  "task_error": null,
  "consumed_credits": 20
}

Параметри

Name
id
Type
path
Description
ID завдання з відповіді на створення.

Повертає

Об'єкт завдання Рельєфу.

DELETE/openapi/v1/relief/:id

Видалення завдання Рельєфу

Остаточно видаляє завдання Рельєфу, включно з його моделлю, картою глибини та даними. Скасувати видалення неможливо.

Request

DELETE

/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20 \
  -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 keeps 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."
}

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

Name
id
Type
path
Description
Ідентифікатор завдання для видалення.

Статус завдання

Видалення завдання зі статусом PENDING повертає кредити, витрачені під час його створення.

Завдання зі статусом IN_PROGRESS видалити не можна. Запит повертає 409 Conflict, а завдання продовжує виконуватися. Meshy не повертає кредити за завдання, яке вже розпочалося, тому видалення призвело б до втрати і кредитів, і результату. Зачекайте, поки воно не досягне статусу SUCCEEDED або FAILED, а потім видаліть його.

Видалення завдання зі статусом SUCCEEDED не повертає кредити. За завдання зі статусом FAILED кредити вже були повернуті після його невдалого завершення.

Повертає

200 OK, коли завдання видалено, або 409 Conflict, коли завдання має статус IN_PROGRESS.

GET/openapi/v1/relief

Список завдань Рельєфу

Повертає список ваших завдань Рельєфу.

Request

GET

/openapi/v1/relief

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

Response

[
  {
    "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
    "type": "relief",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
    },
    "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000060000,
    "expires_at": 1700259260000,
    "task_error": null,
    "consumed_credits": 20
  }
]

Параметри

Name
page_num
Type
integer
Description
Номер сторінки для повернення. Починається з та за замовчуванням дорівнює 1.
Name
page_size
Type
integer
Description
Кількість завдань на сторінці, до 100. За замовчуванням 10. Meshy трактує значення від 101 до 255 як 100, а більше значення повертає 400.
Name
sort_by
Type
string
Description
Порядок сортування.
Доступні значення:
- +created_at: спочатку найстаріші
- -created_at: спочатку найновіші

Повертає

Пагінований список об'єктів завдання Рельєфу.

GET/openapi/v1/relief/:id/stream

Отримати потік задачі Рельєфу

Транслює оновлення задачі Рельєфу у вигляді Server-Sent Events (SSE).

Request

GET

/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/stream

curl -N https://api.meshy.ai/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/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 (other task fields omitted here for brevity;
// each frame is the full task object).
event: message
data: {
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "type": "relief",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
  },
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000060000,
  "expires_at": 1700259260000,
  "task_error": null,
  "consumed_credits": 20
}

Параметри

Name
id
Type
path
Description
ID задачі з відповіді на створення.

Повертає

Потік об'єктів задачі Рельєфу у вигляді Server-Sent Events.

Кожна подія message містить повний об'єкт задачі — той самий, що повертає Отримати задачу Рельєфу. Поки задача перебуває у стані PENDING або IN_PROGRESS, поля, що змінюються між подіями, це progress, status, started_at та preceding_tasks (присутнє лише доки попереду цієї задачі є інші). model_urls, depth_map_url та thumbnail_url отримують значення, коли задача досягає стану SUCCEEDED. Для задачі лише з картою глибини model_urls залишається {}, а thumbnail_url — порожнім.

Подія error містить лише status_code та message, тому перш ніж читати status, перевіряйте назву події.

Об'єкт завдання Рельєф

Об'єкт завдання Рельєф описує один рельєф, створений з фотографії. model_urls, depth_map_url та thumbnail_url завжди присутні та порожні, доки завдання не виконається успішно.

The Relief Task Object

{
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "type": "relief",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
  },
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000060000,
  "expires_at": 1700259260000,
  "task_error": null,
  "consumed_credits": 20
}

Depth map only

{
  "id": "0199c3d2-6b8f-7c25-8f3a-4d9e2b7c5a31",
  "type": "relief",
  "model_urls": {},
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-6b8f-7c25-8f3a-4d9e2b7c5a31/output/depth.png?Expires=***",
  "thumbnail_url": "",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1700259230000,
  "task_error": null,
  "consumed_credits": 20
}

Name
id
Type
string
Description
ID завдання. Розглядайте його як непрозорий рядок і не покладайтеся на його формат.
Name
type
Type
string
Description
Тип завдання, завжди relief.
Name
model_urls
Type
object
Description
URL-адреси для завантаження моделі рельєфу. Файли можуть бути великими; mesh_resolution наводить типові розміри.
- Name
  glb
  Type
  string
  Description
  Файл GLB без текстури. Його одиниці виміру — метри. Відсутній для завдання лише з картою глибини.
- Name
  stl
  Type
  string
  Description
  Та сама модель у вигляді бінарного файлу STL. Її одиниці виміру — міліметри, тож вона відкривається в реальному розмірі рельєфу, з віссю Z нагору. Відсутній для завдання лише з картою глибини.
Name
depth_map_url
Type
string
Description
URL-адреса для завантаження 16-бітної карти глибини у відтінках сірого, на основі якої побудовано рельєф. Яскравіші пікселі — вищі. Значення є відносними висотами, не міліметрами. Програмне забезпечення для лазерного гравіювання та ЧПУ може використовувати її як карту висот. Файл має розмір приблизно 1–2 МБ. Порожнє, якщо такої немає.
Name
thumbnail_url
Type
string
Description
URL-адреса для завантаження попереднього зображення моделі рельєфу. Порожнє, якщо його не було згенеровано, включно із завданнями лише з картою глибини.
Name
progress
Type
integer
Description
Наскільки виконано завдання, у відсотках. Дорівнює 0, доки завдання не почнеться, і 100, коли воно завершиться успішно.
Name
status
Type
string
Description
Статус завдання, один із PENDING, IN_PROGRESS, SUCCEEDED або FAILED.
Name
preceding_tasks
Type
integer
Description
Кількість завдань попереду цього в черзі. Поле опускається, коли значення дорівнює 0, тому воно з'являється лише поки перед цим завданням є інші.
Name
created_at
Type
timestamp
Description
Час створення завдання, у мілісекундах Unix.
Name
started_at
Type
timestamp
Description
Час початку завдання, у мілісекундах Unix. Дорівнює 0, доки завдання не почнеться.
Name
finished_at
Type
timestamp
Description
Час завершення завдання, у мілісекундах Unix. Дорівнює 0, доки завдання не завершиться.
Name
expires_at
Type
timestamp
Description
Час, коли результат завдання стає недійсним, у мілісекундах Unix. Дорівнює 0, доки завдання не завершиться.
Name
task_error
Type
object
Description
Деталі помилки, якщо завдання завершилося невдачею. Див. Помилки.
Name
consumed_credits
Type
integer
Description
Кількість кредитів, використаних завданням: 20, або 0 для завдання зі статусом FAILED, які Meshy повертає.