Retexture API — это функция, которая позволяет интегрировать возможности ИИ-ретекстурирования Meshy в ваше собственное приложение. В этом разделе вы найдёте всю информацию,
необходимую для начала работы с этим API.
Этот эндпоинт позволяет создать новую задачу ретекстурирования. Обратитесь к
объекту задачи ретекстурирования, чтобы увидеть,
какие свойства включены в объект задачи ретекстурирования.
Параметры
Обязателен только один из параметров 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, Изображение в 3D или Ремешинг. Кроме того, она должна иметь статус 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 AI-модели, используемой для ретекстурирования. Доступные значения: meshy-6-lite, 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, за исключением texture_resolution: 8k. meshy-6-lite, 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" и ai_model: "meshy-6-lite" внедряются постепенно и могут быть ещё не включены для вашей учётной записи.
Недопустимая исходная задача: 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}
Этот эндпоинт безвозвратно удаляет задачу ретекстурирования, включая все связанные модели и данные. Это действие необратимо.
Параметры пути
Name
id
Type
path
Description
ID задачи ретекстурирования, которую нужно удалить.
Статус задачи
Задача, которая всё ещё находится в статусе PENDING, удаляется, а
кредиты, потраченные при её создании, возвращаются.
Задача, которая уже находится в статусе IN_PROGRESS, не может быть удалена:
запрос отклоняется с ошибкой 409 Conflict, и задача продолжает выполняться.
Кредиты за задачу, которую воркер уже начал выполнять, не подлежат возврату,
поэтому удаление её в процессе выполнения обойдётся вам одновременно и
потерей кредитов, и результата. Дождитесь, пока она перейдёт в статус
SUCCEEDED, FAILED или CANCELED, а затем удалите её.
Задача в конечном статусе (SUCCEEDED, FAILED или CANCELED) удаляется
без возврата средств.
Возвращает
Возвращает 200 OK при успехе или 409 Conflict, если задача находится в
статусе IN_PROGRESS.
// 200 OK on success, with an empty body.//// 409 Conflict when the task is IN_PROGRESS — the task is left 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."}
[ {"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
Ссылка для скачивания файла текстурированной 3D модели, сгенерированной Meshy.
Name
glb
Type
string
Description
Ссылка для скачивания файла GLB.
Name
fbx
Type
string
Description
Ссылка для скачивания файла FBX.
Name
obj
Type
string
Description
Ссылка для скачивания файла OBJ.
Name
usdz
Type
string
Description
Ссылка для скачивания файла USDZ.
Name
mtl
Type
string
Description
Ссылка для скачивания файла MTL, возвращается вместе с экспортом OBJ при наличии текстур.
Name
stl
Type
string
Description
Ссылка для скачивания файла STL.
Name
3mf
Type
string
Description
Ссылка для скачивания файла 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
Ссылки для скачивания референсных изображений Мультивида, которые были использованы для создания задачи текстурирования. Присутствует только если задача была создана с multiview_image_urls.
Name
thumbnail_url
Type
string
Description
Ссылка для скачивания миниатюры изображения файла модели.
Name
alpha_thumbnail_url
Type
string
Description
Ссылка для скачивания версии 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
Ссылка для скачивания изображения карты базового цвета.
Name
metallic
Type
string
Description
Ссылка для скачивания изображения карты металличности.
Если задача создана с enable_pbr: false, это свойство будет отсутствовать.
Name
normal
Type
string
Description
Ссылка для скачивания изображения карты нормалей.
Если задача создана с enable_pbr: false, это свойство будет отсутствовать.
Name
roughness
Type
string
Description
Ссылка для скачивания изображения карты шероховатости.
Если задача создана с enable_pbr: false, это свойство будет отсутствовать.
Name
emission
Type
string
Description
Ссылка для скачивания изображения карты излучения.
Если задача создана с enable_pbr: false, или ai_model равен meshy-6-lite, это свойство будет отсутствовать.
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}