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, с ID новой задачи 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
ID задачи, которую нужно удалить.

Статус задачи

Удаление задачи со статусом 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 и по умолчанию равен 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 проверяйте название события.

Объект задачи Relief

Объект задачи Relief описывает один рельеф, созданный из фотографии. 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 возвращает.