Retexture API — это функция, которая позволяет интегрировать возможности Meshy по AI-ретекстурированию в ваше собственное приложение. В этом разделе вы найдете всю
необходимую информацию для начала работы с этим API.
Этот эндпоинт позволяет вам создать новую задачу ретекстурирования. Обратитесь к
Объект задачи ретекстурирования, чтобы увидеть, какие
свойства включены в объект задачи ретекстурирования.
Параметры
Только один из input_task_id или model_urlобязателен. Если оба предоставлены, приоритет отдается input_task_id.
Name
input_task_id
Type
string
Обязательный
Description
Идентификатор завершенной задачи Изображение в 3D или Текст в 3D, которую вы хотите переобработать.
Эта задача должна быть одной из следующих: Предпросмотр Текст в 3D, Уточнение Текст в 3D, Изображение в 3D или Ремешинг. Кроме того, у неё должен быть статус SUCCEEDED.
Name
model_url
Type
string
Обязательный
Description
Предоставьте 3D модель для ретекстурирования в Meshy. Поддерживаемые форматы: .glb, .gltf, .obj, .fbx, .stl.
Есть два способа предоставить модель:
Публично доступный URL: URL, доступный из публичного интернета.
Data URI: base64-кодированный data URI модели. Используйте MIME type application/octet-stream. Пример: data:application/octet-stream;base64,<ваши base64-кодированные данные модели>.
Точно один стиль ввода обязателен: text_style_prompt, image_style_url или multiview_image_urls. multiview_image_urls не может быть объединен с любым из двух других; если предоставлены оба text_style_prompt и image_style_url, приоритет отдается image_style_url.
Name
text_style_prompt
Type
string
Обязательный
Description
Опишите желаемый стиль текстуры объекта с помощью текста. Максимум 600 символов.
Name
image_style_url
Type
string
Обязательный
Description
Предоставьте 2D изображение, чтобы направить процесс текстурирования. В настоящее время мы поддерживаем форматы .jpg, .jpeg и .png.
Есть два способа предоставить изображение:
Публично доступный URL: URL, доступный из публичного интернета
Data URI: base64-кодированный data URI изображения. Пример data URI: data:image/jpeg;base64,<ваши base64-кодированные данные изображения>
Текстурирование изображения может работать не оптимально, если есть существенные различия геометрии между оригинальным asset и загруженным изображением.
Name
multiview_image_urls
Type
string[]
Обязательный
Description
Предоставьте от 1 до 4 изображений, показывающих один и тот же объект с разных точек зрения, чтобы направить текстурирование. Первое изображение — это основной (фронтальный) вид; порядок оставшихся видов (левый, задний, правый) не имеет значения.
Каждый элемент принимает те же форматы, что и image_style_url (публично доступный URL или data URI в формате base64, .jpg/.jpeg/.png).
Требуется ai_model: "meshy-7" (или latest).
Name
ai_model
Type
string
по умолчанию latest
Description
Идентификатор AI модели, используемой для ретекстурирования. Доступные значения: meshy-5, meshy-6, meshy-7, latest (Meshy 7).
Name
enable_original_uv
Type
boolean
по умолчанию false
Description
Сохраняйте существующую UV-раскладку модели вместо генерации новой.
Если вы ретекстурируете модель, созданную Meshy (через input_task_id или model_url, который указывает на вывод Meshy), установите это значение в true, чтобы повторно использовать оптимизированную UV-раскладку.
Если вы ретекстурируете стороннюю модель, которую вы загрузили, установите true, если она уже имеет хорошие UV-развертки, которые вы хотите сохранить, или оставьте false, чтобы Meshy разворачивал новые UV-развертки (лучше всего для моделей, у которых нет соответствующей UV-развертки).
Name
enable_pbr
Type
boolean
по умолчанию false
Description
Генерируйте PBR-карты (металлическую, шероховатость, нормали) в дополнение к базовому цвету. Также включена карта эмиссии, если ai_model — meshy-6, кроме текстур высокого разрешения 8k. meshy-7 и latest не создают карту эмиссии.
Name
texture_resolution
Type
string
по умолчанию 2k
Description
Разрешение текстуры базового цвета. Одно из 2k (2048×2048), 4k (4096×4096) или 8k (8192×8192). Более высокие разрешения позволяют уловить больше деталей поверхности.
4k и 8k требуют ai_modelmeshy-6, meshy-7 или latest. На 8k карта эмиссии не создается.
Name
hd_texture
Type
boolean
⚠ устаревший
по умолчанию false
Description
Используйте texture_resolution вместо — эквивалентен texture_resolution: "4k". Когда заданы оба параметра, приоритет имеет texture_resolution.
Name
remove_lighting
Type
boolean
по умолчанию true
Description
Удаляет блики и тени из текстуры базового цвета, создавая более чистый результат, который лучше подходит для собственных настроек освещения.
Поддерживается только когда ai_model — meshy-6.
Name
target_formats
Type
string[]
Description
Указывает, какие 3D форматы файлов включить в вывод. Будут сгенерированы и возвращены только запрошенные форматы, что может сократить время выполнения задачи. Если не указано, включаются все поддерживаемые форматы.
Доступные значения: glb, obj, fbx, stl, usdz, 3mf
Если параметр не указан, все форматы кроме 3mf сгенерированы. 3mf включен только при явном указании.
Name
alpha_thumbnail
Type
boolean
по умолчанию false
Description
Если установлено true, задача дополнительно рендерит версию предпросмотра с прозрачным фоном (RGBA) и возвращает его как alpha_thumbnail_url в ответе на GET-запрос. Существующее поле thumbnail_url остается неизменным.
Возвращает
Свойство result в ответе содержит id задачи вновь созданной задачи ретекстурирования.
Режимы отказа
Name
400 - Bad Request
Description
Запрос был неприемлем. Частые причины:
Отсутствует параметр: Необходимо предоставить либо model_url, либо input_task_id.
Отсутствует стиль: Необходимо предоставить один из text_style_prompt, image_style_url или multiview_image_urls.
Конфликтующие входы стилей: multiview_image_urls нельзя объединить с text_style_prompt или image_style_url.
Неподдерживаемая модель для многовидов: multiview_image_urls требует ai_model: "meshy-7" (или latest).
Модель недоступна: ai_model: "meshy-7" разворачивается прогрессивно и еще не доступен для вашего аккаунта.
Недопустимая задача ввода: input_task_id должен ссылаться на успешную задачу из поддерживаемой модели.
Недопустимый формат модели: model_url указывает на файл с неподдерживаемым расширением.
Недоступный URL: model_url, image_style_url или элемент multiview_image_urls не может быть загружен.
Name
401 - Unauthorized
Description
Аутентификация не удалась. Пожалуйста, проверьте ваш API-ключ.
Name
402 - Payment Required
Description
Недостаточно кредитов для выполнения этой задачи.
Name
429 - Too Many Requests
Description
Вы превысили ваше ограничение частоты.
Запрос
POST
/openapi/v1/retexture
# Ретекстурирование с текстовым promptcurlhttps://api.meshy.ai/openapi/v1/retexture \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "model_url": "https://cdn.meshy.ai/model/example_model_2.glb", "text_style_prompt": "red fangs, Samurai outfit that fused with japanese batik style", "enable_original_uv": true, "enable_pbr": true }'# Ретекстурирование с изображением стиля и PBRcurlhttps://api.meshy.ai/openapi/v1/retexture \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "model_url": "https://cdn.meshy.ai/model/example_model_2.glb", "image_style_url": "https://cdn.meshy.ai/image/example_image.jpg", "ai_model": "latest", "enable_pbr": true, "enable_original_uv": true }'
Этот эндпоинт позволяет вам получить задачу ретекстурирования, указывая ее действительный id.
Обратитесь к Объект задачи ретекстурирования, чтобы увидеть, какие
свойства включены в объект задачи ретекстурирования.
Параметры
Name
id
Type
path
Description
Уникальный идентификатор задачи ретекстурирования для получения.
{"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***","fbx":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***","obj":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***","usdz":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***","mtl":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***","stl":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***" },"thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","text_style_prompt":"red fangs, Samurai outfit that fused with japanese batik style","texture_image_url":"","progress":100,"started_at":1692771667037,"created_at":1692771650657,"expires_at":1692771679037,"finished_at":1692771669037,"status":"SUCCEEDED","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***","metallic":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX","normal":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX","roughness":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX","emission":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX" } ],"task_error": {"message":"" },"consumed_credits":10}
[ {"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***","fbx":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***","usdz":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***" },"thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","text_style_prompt":"red fangs, Samurai outfit that fused with japanese batik style","progress":100,"started_at":1692771667037,"created_at":1692771650657,"expires_at":1692771679037,"finished_at":1692771669037,"status":"SUCCEEDED","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***","metallic":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX","normal":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX","roughness":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX","emission":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX" } ],"preceding_tasks":0,"task_error": {"message":"" },"consumed_credits":10 }]
// Пример события ошибкиevent: errordata: {"status_code": 404,"message": "Task not found"}// Примеры событий сообщения иллюстрируют прогресс задачи.// Для задач в статусе PENDING или IN_PROGRESS поток ответа не будет включать все поля.event: messagedata: {"id": "018a210d-8ba4-705c-b111-1f1776f7f578","progress": 0,"status": "PENDING"}event: messagedata: {"id": "018a210d-8ba4-705c-b111-1f1776f7f578","progress": 50,"status": "IN_PROGRESS"}event: messagedata: {"id": "018a210d-8ba4-705c-b111-1f1776f7f578","type": "retexture","progress": 100,"status": "SUCCEEDED","created_at": 1692771650657,"started_at": 1692771667037,"finished_at": 1692771669037,"model_urls": {"glb":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***","fbx":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***","obj":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***","usdz":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***","mtl":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***","stl":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***" },"texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***","metallic":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX","normal":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX","roughness":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX","emission":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX" } ],"preceding_tasks": 0,"task_error": {"message":"" },"consumed_credits": 10}
Объект задачи ретекстурирования — это рабочая единица, используемая Meshy для генерации 3D текстуры из текстовых или графических входов.
Модель имеет следующие свойства:
Свойства
Name
id
Type
string
Description
Уникальный идентификатор для задачи. Хотя мы используем k-сортируемый UUID для идентификаторов задач как
детали реализации, вы не должны делать каких-либо предположений о формате идентификатора.
Name
type
Type
string
Description
Тип задачи ретекстурирования. Значение — retexture.
Name
model_urls
Type
object
Description
URL для скачивания текстурированной 3D модели, сгенерированной Meshy.
Name
glb
Type
string
Description
URL для скачивания GLB файла.
Name
fbx
Type
string
Description
URL для скачивания FBX файла.
Name
obj
Type
string
Description
URL для скачивания OBJ файла.
Name
usdz
Type
string
Description
URL для скачивания USDZ файла.
Name
mtl
Type
string
Description
URL для скачивания MTL файла, возвращаемого вместе с экспортами OBJ, когда присутствуют текстуры.
Name
stl
Type
string
Description
URL для скачивания STL файла.
Name
3mf
Type
string
Description
URL для скачивания 3MF файла. Присутствует только когда 3mf был запрошен через target_formats.
Name
text_style_prompt
Type
string
Description
Это текстовое описание, использованное для создания задачи текстурирования.
Name
image_style_url
Type
string
Description
Это изображение, использованное в качестве ввода для создания задачи текстурирования.
Name
multiview_image_urls
Type
string[]
Description
URL для скачивания изображений с несколькими видами, которые были использованы для создания задачи текстурирования. Присутствует только когда задача была создана с multiview_image_urls.
Name
thumbnail_url
Type
string
Description
URL для скачивания миниатюры изображения файла модели.
Name
alpha_thumbnail_url
Type
string
Description
URL для скачивания версии thumbnail_url с прозрачным фоном (RGBA). Присутствует только когда задача была создана с alpha_thumbnail: true и прозрачная версия предпросмотра была успешно отрендерена; в противном случае это поле опускается.
Name
progress
Type
integer
Description
Прогресс задачи. Если задача ещё не начата, это свойство будет 0. После успешного завершения задачи оно станет 100.
Name
started_at
Type
timestamp
Description
Временная метка начала задачи, в миллисекундах. Если задача ещё не начата, это свойство будет 0.
Временная метка представляет собой число миллисекунд, прошедших с 1 января 1970 года по UTC, согласно
стандарту RFC 3339.
Например, пятница, 1 сентября 2023 года, 12:00:00 PM GMT представляется как 1693569600000. Это применяется
ко всем временным меткам в Meshy API.
Name
created_at
Type
timestamp
Description
Временная метка создания задачи, в миллисекундах.
Name
expires_at
Type
timestamp
Description
Временная метка истечения срока действия результата задачи, в миллисекундах.
Name
finished_at
Type
timestamp
Description
Временная метка завершения задачи, в миллисекундах. Если задача ещё не завершена, это свойство будет 0.
Name
status
Type
string
Description
Статус задачи. Возможные значения: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Массив объектов URL текстур, сгенерированных из задачи. Обычно он содержит только один объект URL текстуры. Каждый URL текстуры имеет следующие свойства:
Name
base_color
Type
string
Description
URL для скачивания изображения базовой цветовой карты.
Name
metallic
Type
string
Description
URL для скачивания изображения металлической карты.
Если задача создана с enable_pbr: false, это свойство будет опущено.
Name
normal
Type
string
Description
URL для скачивания изображения карты нормалей.
Если задача создана с enable_pbr: false, это свойство будет опущено.
Name
roughness
Type
string
Description
URL для скачивания изображения карты шероховатости.
Если задача создана с enable_pbr: false, это свойство будет опущено.
Name
emission
Type
string
Description
URL для скачивания изображения карты эмиссии.
Если задача создана с enable_pbr: false, или ai_model — meshy-5, это свойство будет опущено.
Name
preceding_tasks
Type
integer
Description
Количество предыдущих задач.
Это свойство присутствует только когда статус задачи PENDING.
Name
task_error
Type
object
Description
Детали ошибки для провалившихся задач. См. Ошибки для полного справочника по объекту task_error.
Name
consumed_credits
Type
integer
Description
Количество кредитов, потребленных задачей. Присутствует, когда статус задачи PENDING, IN_PROGRESS или SUCCEEDED. Возвращает 0 для задач со статусом FAILED (кредиты возмещаются при сбое).
Пример модели задачи ретекстурирования
{"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***","fbx":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***","usdz":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***" },"text_style_prompt":"red fangs, Samurai outfit that fused with japanese batik style","image_style_url":"https://assets.meshy.ai/***/image/example_image.jpg?Expires=***","thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","progress":100,"started_at":1692771667037,"created_at":1692771650657,"expires_at":1692771679037,"finished_at":1692771669037,"status":"SUCCEEDED","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***","metallic":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX","normal":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX","roughness":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX","emission":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX" } ],"preceding_tasks":0,"task_error": {"message":"" },"consumed_credits":10}