API Ретекстурування

API Ретекстурування — це функція, яка дає змогу інтегрувати можливості 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 або Ремеш. Крім того, воно повинно мати статус 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,<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: закодований у base64 Data URI зображення. Приклад 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) на додаток до базового кольору. Карта емісії також включається, коли 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
Прогрес завдання. Якщо завдання ще не запущено, ця властивість буде 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
}