Ретекстурирование API — это функция, которая позволяет интегрировать возможности AI ретекстурирования Meshy в ваше собственное приложение. В этом разделе вы найдете всю необходимую информацию, чтобы начать работу с этим API.
Этот эндпоинт позволяет создать новую задачу Ретекстурирования. См.
The Retexture Task Object, чтобы узнать, какие
свойства входят в объект задачи Ретекстурирования.
Параметры
Требуется указать только один из параметров input_task_id или model_url. Если указаны оба, приоритет имеет input_task_id.
Name
input_task_id
Type
string
Обязательный
Description
ID завершённой задачи Изображение в 3D или Текст в 3D, которую вы хотите ретекстурировать.
Эта задача должна быть одной из следующих: Text to 3D Preview, Text to 3D Refine, Image to 3D или Remesh. Кроме того, она должна иметь статус SUCCEEDED.
Публично доступный URL: URL, доступный из публичного интернета.
Data URI: base64-кодированный data URI модели. Используйте MIME type application/octet-stream. Пример: data:application/octet-stream;base64,<your base64-encoded model data>.
Требуется указать ровно один вариант стиля: 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
Опишите желаемый стиль текстуры объекта с помощью текста. Максимум 800 символов.
Name
image_style_url
Type
string
Обязательный
Description
Предоставьте 2D-изображение для управления процессом текстурирования. В настоящее время поддерживаются форматы .jpg, .jpeg и .png.
Изображение можно предоставить двумя способами:
Публично доступный URL: URL, доступный из публичного интернета
Data URI: base64-кодированный data URI изображения. Пример data URI: data:image/jpeg;base64,<your base64-encoded image data>
Текстурирование по изображению может работать не оптимально при значительных различиях в геометрии между исходным объектом и загруженным изображением.
Name
multiview_image_urls
Type
string[]
Обязательный
Description
Предоставьте от 1 до 4 изображений, показывающих один и тот же объект с разных ракурсов, для управления текстурированием. Первое изображение — основной (передний) ракурс; порядок остальных ракурсов (слева, сзади, справа) не важен.
Каждый элемент принимает те же форматы, что и image_style_url (публично доступный URL или base64 data URI, .jpg/.jpeg/.png).
Требует явного указания ai_model: "meshy-7".
Name
ai_model
Type
string
по умолчанию latest
Description
ID 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-карты (metallic, roughness, normal) в дополнение к базовому цвету. Карта эмиссии также включается, когда ai_model равен meshy-6, за исключением texture_resolution: 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".
Модель недоступна: 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
Вы превысили ограничение частоты запросов.
Request
POST
/openapi/v1/retexture
# Retexture with text 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 }'# Retexture with image style and 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 }]
Объект задачи Ретекстурирования — это рабочая единица, которую Meshy использует для генерации 3D текстуры из текстовых или графических входных данных.
Модель имеет следующие свойства:
Свойства
Name
id
Type
string
Description
Уникальный идентификатор задачи. Хотя мы используем k-сортируемый UUID для идентификаторов задач как деталь реализации, вы не должны делать никаких предположений о формате id.
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
Это текстовый prompt, который был использован для создания задачи текстурирования.
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 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}