API ретекстурирования

API ретекстурирования — это функция, которая позволяет интегрировать возможности AI-ретекстурирования Meshy в ваше собственное приложение. В этом разделе вы найдете всю информацию, необходимую для начала работы с этим API.

POST/openapi/v1/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.

Name
model_url
Type
string
Обязательный
Description
Предоставьте 3D-модель, для которой Meshy выполнит текстурирование. Поддерживаемые форматы: .glb, .gltf, .obj, .fbx, .stl.
Есть два способа предоставить модель:
- Публично доступный URL: URL, доступный из публичного интернета.
- Data URI: Data URI модели, закодированный в base64. Используйте MIME type application/octet-stream. Пример: data:application/octet-stream;base64,<your base64-encoded model data>.

Требуется только одно из 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: Data URI изображения, закодированный в base64. Пример Data URI: data:image/jpeg;base64,<your base64-encoded image data>
Текстурирование по изображению может работать неоптимально, если между исходным ассетом и загруженным изображением есть существенные различия в геометрии.

Name
ai_model
Type
string
по умолчанию latest
Description
ID AI-модели, используемой для ретекстурирования. Доступные значения: meshy-5, meshy-6, latest (Meshy 6).
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 или latest.
Name
hd_texture
Type
boolean
по умолчанию false
Description
Генерирует текстуру базового цвета в разрешении 4K (4096×4096) для более высокой детализации.
Поддерживается только когда ai_model — meshy-6 или latest. PBR-карты всегда генерируются в 2K.
Name
remove_lighting
Type
boolean
по умолчанию true
Description
Удаляет блики и тени из текстуры базового цвета, создавая более чистый результат, который лучше работает при пользовательских настройках освещения.
Поддерживается только когда ai_model — meshy-6 или latest.
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.
- Недопустимая входная задача: input_task_id должен ссылаться на успешно выполненную задачу поддерживаемой модели.
- Недопустимый формат модели: model_url указывает на файл с неподдерживаемым расширением.
- Недоступный URL: Не удалось скачать model_url или image_style_url.
Name
401 - Unauthorized
Description
Не удалось выполнить аутентификацию. Проверьте свой API-ключ.
Name
402 - Payment Required
Description
Недостаточно кредитов для выполнения этой задачи.
Name
429 - Too Many Requests
Description
Вы превысили свое ограничение частоты.

Request

POST

/openapi/v1/retexture

# Retexture with text prompt
curl https://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 PBR
curl https://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
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

GET/openapi/v1/retexture/:id

Получение задачи Ретекстурирование

Этот эндпоинт позволяет получить задачу Ретекстурирование по действительному id. См. Объект задачи Ретекстурирование, чтобы узнать, какие свойства включены в объект задачи Ретекстурирование.

Параметры

Name
id
Type
path
Description
Уникальный идентификатор задачи Ретекстурирование, которую нужно получить.

Возвращаемые данные

Ответ содержит объект задачи Ретекстурирование. Подробности см. в разделе Объект задачи Ретекстурирование.

Request

GET

/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "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
}

DELETE/openapi/v1/retexture/:id

Удалить задачу ретекстурирования

Этот эндпоинт безвозвратно удаляет задачу ретекстурирования, включая все связанные модели и данные. Это действие необратимо.

Параметры пути

Name
id
Type
path
Description
ID задачи ретекстурирования, которую нужно удалить.

Возвращает

Возвращает 200 OK при успешном выполнении.

Request

DELETE

/openapi/v1/retexture/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/retexture/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.

GET/openapi/v1/retexture

Список задач Ретекстурирования

Этот эндпоинт позволяет получить список задач Ретекстурирования.

Параметры

Name
page_num
Type
integer
по умолчанию 1
Description
Номер страницы для пагинации.
Name
page_size
Type
integer
по умолчанию 10
Description
Ограничение размера страницы. Максимально допустимое значение — 50 элементов.
Name
sort_by
Type
string
Description
Поле для сортировки.
Доступные значения:
- +created_at: Сортировать по времени создания в порядке возрастания.
- -created_at: Сортировать по времени создания в порядке убывания.

Возвращает

Возвращает пагинированный список объектов задачи Ретекстурирования.

Request

GET

/openapi/v1/retexture

curl https://api.meshy.ai/openapi/v1/retexture?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "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
  }
]

GET/openapi/v1/retexture/:id/stream

Потоковая передача задачи ретекстурирования

Этот эндпоинт передает обновления в реальном времени для задачи ретекстурирования с использованием Server-Sent Events (SSE).

Параметры

Name
id
Type
path
Description
Уникальный идентификатор задачи ретекстурирования для потоковой передачи.

Возвращает

Возвращает поток объектов задачи ретекстурирования как Server-Sent Events.

Для задач PENDING или IN_PROGRESS поток ответа будет включать только необходимые поля progress и status.

Request

GET

/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578/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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
  "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 для идентификаторов задач как деталь реализации, вам не следует делать никаких предположений о формате 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
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
Progress задачи. Если задача еще не запущена, это свойство будет 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 (кредиты возвращаются при сбое).

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
}