Retexture API — это функция, которая позволяет интегрировать возможности ИИ-ретекстурирования Meshy в ваше собственное приложение. В этом разделе вы найдёте всю информацию,
необходимую для начала работы с этим API.
Этот эндпоинт позволяет создать новую задачу Ретекстурирования. Обратитесь к разделу
Объект задачи Retexture, чтобы узнать, какие
свойства включены в объект задачи Retexture.
Параметры
Требуется указать только один из параметров 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,<ваши 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
Опишите желаемый стиль текстуры объекта с помощью текста. Максимум 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,<ваши base64-закодированные данные изображения>
Текстурирование по изображению может работать не оптимально, если между исходным ассетом и загруженным изображением есть существенные различия в геометрии.
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 модели ИИ для использования при ретекстурировании. Доступные значения: 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) в дополнение к базовому цвету. Карта emission также включается, когда ai_model равен meshy-6, за исключением texture_resolution: 8k. meshy-7 и latest не создают карту emission.
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 карта emission не создаётся.
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 задачи вновь созданной задачи Retexture.
Режимы отказа
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 }]
Объект Retexture Task — это единица работы, которую Meshy использует для генерации 3D текстуры на основе текстовых или графических входных данных.
Модель обладает следующими свойствами:
Свойства
Name
id
Type
string
Description
Уникальный идентификатор задачи. Хотя в качестве деталей реализации мы используем k-sortable 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 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 (кредиты возвращаются при неудаче).
Example Retexture Task Model
{"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}