Creative Lab — API лампи

Перетворіть вихідну фотографію на придатний для 3D-друку абажур лампи у два етапи: прототип генерує стилізоване концептуальне зображення в матовому білому кольорі та перетворює його на порожню 3D-модель (GLB), а потім збірка запускає обробник лампи для цієї моделі, щоб отримати придатні для друку деталі STL — абажур з відкритим дном та базовою пластиною для елемента освітлення, а також саме кріплення для цього елемента. Ці два етапи пов'язані через input_task_id.

POST /openapi/creative-lab/lamp/v1/prototype
POST /openapi/creative-lab/lamp/v1/build

POST/openapi/creative-lab/lamp/v1/prototype

Створення завдання прототипу лампи

Згенеруйте єдине матово-біле концептуальне зображення з референсного фото та конвертуйте його в порожнисту 3D-модель абажура лампи. Відповідь містить як концептуальне зображення (image_urls), так і 3D-модель (model_urls.glb з thumbnail_url). Повернений ID завдання — це те, що ви передаєте як input_task_id до кінцевої точки збірки. Зверніться до Об'єкта завдання прототипу лампи для отримання інформації про структуру відповіді.

Параметри

Name
image_url
Type
string
Обов'язковий
Description
Вихідне фото, яке Meshy використовує як візуальний референс для абажура лампи. Ми наразі підтримуємо формати .jpg, .jpeg, .png та .webp.
Існує два способи надати зображення:
- Загальнодоступна URL-адреса: URL-адреса, доступна з публічного інтернету.
- Data URI: закодоване у base64 представлення зображення у форматі data URI. Приклад data URI: data:image/jpeg;base64,<ваші base64-закодовані дані зображення>.

Name
image_subject
Type
string
за замовчуванням character
Description
Підказка щодо категорії суб'єкта, яка вибирає prompt стилізації. Доступні значення:
- character (за замовчуванням) — окремий персонаж / об'єкт (фігурка, тварина, талісман тощо).
- landscape — зовнішня сцена / панорама (гора, міський пейзаж, ліс тощо).
Name
name
Type
string
Description
Необов'язкова назва завдання для відображення. Максимум 100 символів.
Name
remove_background
Type
boolean
за замовчуванням false
Description
Якщо встановлено значення true, зображення прототипу повертається як прозорий RGBA PNG з видаленим фоном, щоб ви могли скомпонувати суб'єкт з будь-яким фоном.

Повертає

Властивість result відповіді містить id новоствореного завдання прототипу лампи. Опитуйте кінцеву точку Отримання завдання або підписуйтеся на потік, доки завдання не досягне статусу SUCCEEDED, потім передайте цей ID до кінцевої точки збірки як input_task_id.

Режими відмов

Name
400 - Bad Request
Description
Запит було неприйнятним. Поширені причини:
- Відсутній параметр: image_url є обов'язковим.
- Недійсний формат зображення: наданий image_url не відповідає підтримуваному формату (.jpg, .jpeg, .png, .webp).
- Розміри зображення поза допустимим діапазоном: зображення занадто мале, перевищує максимальний розмір файлу або перевищує максимальну кількість пікселів.
- Недоступна URL-адреса: image_url не вдалося завантажити (404 або timeout).
- Недійсний Data URI: рядок base64 має неправильний формат.
- Позначено вміст: вхідне зображення було позначено moderation NSFW або інтелектуальної власності.
- Недійсний image_subject: не є одним із character / landscape.
Name
401 - Unauthorized
Description
Автентифікація не вдалася. Будь ласка, перевірте свій API-ключ.
Name
402 - Payment Required
Description
Недостатньо кредитів для виконання цього завдання.
Name
429 - Too Many Requests
Description
Ви перевищили своє обмеження частоти.

Request

POST

/openapi/creative-lab/lamp/v1/prototype

# Stage 1: concept image + hollow 3D lampshade model from a source photo
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/prototype \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "image_subject": "character"
  }'

Response

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

Prototype example

Start with a source photo; the prototype returns the concept image and a hollow 3D model that the build stage processes.

Source cat photo used as the Creative Lab Lamp input — Prototype input

Creative Lab Lamp prototype output generated from the source photo — Prototype output

POST/openapi/creative-lab/lamp/v1/build

Створення завдання побудови лампи

Генерує фінальні придатні для 3D-друку частини на основі успішного завдання прототипу. Побудова запускає процесор лампи на 3D-моделі прототипу: масштабує модель до diameter_mm, вирівнює низ на cut_amount_percent, робить порожнистою до thickness_mm, відкриває низ і — коли обрано пресет кріплення — додає базову пластину з отвором для кріплення та окреме кріплення для джерела світла. Дивіться Об'єкт завдання побудови лампи щодо форми відповіді.

Параметри

Name
input_task_id
Type
string
Обов'язковий
Description
Ідентифікатор завдання прототипу, створеного через цю саму кінцеву точку OpenAPI. Прототип мав бути створений з тим самим API-ключем, мав досягти статусу SUCCEEDED і мав створити 3D-модель.
Завдання прототипу, створені через веб-застосунок, не приймаються — кінцева точка побудови приймає лише завдання прототипу, створені через POST /openapi/creative-lab/lamp/v1/prototype, і відхиляє будь-яке інше джерело з кодом 404.
Name
name
Type
string
Description
Необов'язкова назва завдання для відображення. Максимум 100 символів.

`options`

Необов'язкові параметри налаштування геометрії абажура. Кожне поле має розумне значення за замовчуванням — надсилайте лише ті, які хочете перевизначити.

Name
diameter_mm
Type
number
за замовчуванням 150
Description
Цільовий максимальний розмір обмежувального паралелепіпеда абажура, у міліметрах. Сітка рівномірно масштабується, щоб відповідати цьому розміру. Діапазон: [50, 400].
Name
thickness_mm
Type
number
за замовчуванням 1
Description
Товщина стінки порожнистого абажура, у міліметрах. Діапазон: (0, 10].
Name
cut_amount_percent
Type
number
за замовчуванням 1
Description
Відсоток висоти моделі, що зрізається пласко внизу, щоб абажур розташовувався на друкувальному столі та мав отвір для кріплення. Діапазон: [1, 100].
Name
light_source_preset
Type
string
за замовчуванням bambu_mh001_60mm
Description
Пресет кріплення джерела світла, який визначає, як будується низ. Доступні значення:
- bambu_mh001_60mm (за замовчуванням) — абажур з відкритим низом плюс базова пластина з отвором для кріплення 60 мм, обидва в model_urls.lamp_stl, і кріплення для фіксатора як model_urls.base_stl.
- none — єдиний закритий абажур у model_urls.lamp_stl; model_urls.base_stl пропускається.
Name
fixture_offset_x_mm
Type
number
за замовчуванням 0
Description
Зміщення отвору для кріплення на базовій пластині вздовж осі X відносно центру абажура, у міліметрах. Має значення лише коли light_source_preset ≠ none. Діапазон: [-80, 80].
Name
fixture_offset_z_mm
Type
number
за замовчуванням 0
Description
Зміщення отвору для кріплення на базовій пластині вздовж осі Z (глибина) відносно центру абажура, у міліметрах. Має значення лише коли light_source_preset ≠ none. Діапазон: [-80, 80].
Name
rotate_x_deg
Type
number
за замовчуванням 0
Description
Обертання навколо осі X, застосоване до моделі перед обробкою, у градусах. Три обертання застосовуються як кути Ейлера XYZ відносно центру моделі. Діапазон: [-360, 360].
Name
rotate_y_deg
Type
number
за замовчуванням 0
Description
Обертання навколо осі Y, застосоване до імпортованої сітки перед обробкою, у градусах. Діапазон: [-360, 360].
Name
rotate_z_deg
Type
number
за замовчуванням 0
Description
Обертання навколо осі Z, застосоване до імпортованої сітки перед обробкою, у градусах. Діапазон: [-360, 360].
Name
include_result_json
Type
boolean
за замовчуванням false
Description
Коли true і output.format дорівнює zip, включає result.json процесора лампи (назва конвеєра, попередження та шляхи артефактів) до пакунка. Ігнорується, коли output.format дорівнює stl.

`output`

Необов'язковий селектор формату передачі. За замовчуванням stl.

Name
format
Type
string
за замовчуванням stl
Description
Пакунок артефактів, що повертається побудовою. Доступні значення:
- stl (за замовчуванням) — повертає model_urls.lamp_stl (абажур разом із базовою пластиною, якщо встановлено пресет кріплення), плюс model_urls.base_stl, коли light_source_preset ≠ none.
- zip — упаковує кожен артефакт, що видає процесор (lamp.stl, необов'язковий base.stl, необов'язковий result.json), в один zip-архів і повертає його під model_urls.bundle_zip.

Повертає

Властивість result відповіді містить id завдання щойно створеного завдання побудови лампи. Опитуйте кінцеву точку Отримати завдання або підпишіться на потік, поки завдання не досягне статусу SUCCEEDED, а потім завантажте артефакти з model_urls.

Режими помилок

Name
400 - Bad Request
Description
Запит неприйнятний. Поширені причини:
- Відсутній параметр: input_task_id є обов'язковим.
- Недійсний UUID: input_task_id не є дійсним UUID.
- Батьківське завдання не завершено успішно: Зазначене завдання прототипу ще не досягло статусу SUCCEEDED.
- Немає моделі: Завдання прототипу завершилося успішно, але не створило 3D-модель.
- Параметри поза діапазоном: Одне з полів options вийшло за межі допустимого діапазону або набору значень enum.
Name
401 - Unauthorized
Description
Автентифікація не вдалася. Перевірте свій API-ключ.
Name
402 - Payment Required
Description
Недостатньо кредитів для виконання цього завдання.
Name
404 - Not Found
Description
Зазначене завдання прототипу не існує, належить іншому користувачеві або було створене через веб-застосунок (лише завдання прототипу в режимі API можуть переходити до побудови).
Name
429 - Too Many Requests
Description
Ви перевищили обмеження частоти запитів.

Request

POST

/openapi/creative-lab/lamp/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "options": {
      "diameter_mm": 120,
      "thickness_mm": 2,
      "light_source_preset": "bambu_mh001_60mm",
      "cut_amount_percent": 30
    },
    "output": {
      "format": "stl"
    }
  }'

Response

{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}

Приклад побудови

Завдання побудови перетворює 3D-модель прототипу на придатні для друку частини абажура.

Попередній перегляд моделі побудови лампи Creative Lab — Попередній перегляд моделі побудови

GET/openapi/creative-lab/lamp/v1/(prototype|build)/:id

Отримати завдання лампи

Отримати завдання прототипу або збірки за дійсним id завдання. Шлях URL має відповідати етапу завдання — завдання збірки, отримане через /prototype/:id, повертає 404, і навпаки.

Зверніться до Об'єкта завдання прототипу лампи та Об'єкта завдання збірки лампи для ознайомлення з формами відповіді.

Параметри

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

Повертає

Відповідь містить об'єкт завдання лампи. Форма залежить від того, який етап було запитано.

Request

GET

/openapi/creative-lab/lamp/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

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

# Build
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-lamp-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-lamp-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "lamp_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/lamp.stl?Expires=***",
    "base_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/base.stl?Expires=***"
  }
}

DELETE/openapi/creative-lab/lamp/v1/(prototype|build)/:id

Delete a Lamp Task

Скасувати завдання лампи. Якщо завдання ще перебуває у стані PENDING, кредити, витрачені під час створення, повертаються. Завдання, що вже перебувають у стані IN_PROGRESS, скасовуються без повернення коштів (виконавець може вже витрачати ресурси). Завдання, що вже досягли кінцевого стану (SUCCEEDED, FAILED, CANCELED), не можуть бути скасовані.

Шлях URL має відповідати етапу завдання — DELETE для /prototype/:buildId повертає 404.

Параметри шляху

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

Повертає

Повертає 204 No Content у разі успіху з порожнім тілом відповіді.

Режими помилок

Name
400 - Bad Request
Description
Завдання вже перебуває у кінцевому стані і не може бути скасоване.
Name
404 - Not Found
Description
Завдання не існує, належить іншому користувачу, або його етап не відповідає шляху URL.

Request

DELETE

/openapi/creative-lab/lamp/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/lamp/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 204 No Content on success (empty body).

GET/openapi/creative-lab/lamp/v1/(prototype|build)/:id/stream

Потокова передача завдання Lamp

Отримуйте оновлення в реальному часі для завдання лампи через Server-Sent Events (SSE). Шлях URL має відповідати етапу завдання — відкриття потоку за адресою /prototype/:buildId/stream видає єдине корисне навантаження event: error зі status_code: 404 і закриває потік.

Параметри

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

Повертає

Повертає потік об'єктів завдання Lamp Prototype або Lamp Build у вигляді Server-Sent Events. Кожен кадр містить повний об'єкт завдання для цього етапу — таку саму форму, яку повертає кінцева точка Get, — тому поки завдання має статус PENDING або IN_PROGRESS, поля виводу просто ще не заповнені (null, [] або {}), а finished_at дорівнює null.

Request

GET

/openapi/creative-lab/lamp/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream

curl -N https://api.meshy.ai/openapi/creative-lab/lamp/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (wrong stage or task not found)
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// Every frame is the full task object; fields not yet populated are null / empty.
// The PENDING frame below is abbreviated to the fields that change.
event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-lamp-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "lamp_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/lamp.stl?Expires=***",
    "base_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/base.stl?Expires=***"
  }
}

GET/openapi/creative-lab/lamp/v1/(prototype|build)

Список завдань лампи

Отримайте пагінований список ваших завдань лампи для одного етапу. Шлях URL визначає етап — /prototype повертає завдання прототипу; /build повертає завдання збірки. Завдання з іншого етапу не включаються до жодної відповіді.

Параметри шляху

Name
stage
Type
path
Обов'язковий
Description
Або prototype, або build. Колекція повертає лише завдання, етап яких відповідає URL — запит до /prototype ніколи не повертає завдання збірки, і навпаки.

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

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

Повертає

Повертає пагінований список об'єктів завдання для відповідного етапу — або об'єкт завдання прототипу лампи при перегляді /prototype, або об'єкт завдання збірки лампи при перегляді /build.

Request

GET

/openapi/creative-lab/lamp/v1/prototype

# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/prototype?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/build?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-lamp-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123486000,
    "expires_at": 1729382686000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 30,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

Об'єкт Lamp Prototype Task

Об'єкт Lamp Prototype Task — це одиниця роботи, яку Meshy відстежує для створення стилізованого матово-білого концептуального зображення з вихідної фотографії та конвертації його в порожнисту 3D-модель. Результат цього етапу передається на етап побудови через input_task_id.

Властивості

Name
id
Type
string
Description
Унікальний ідентифікатор завдання. Хоча як деталь реалізації ми використовуємо k-сортований UUID для ідентифікаторів завдань, вам не слід робити жодних припущень щодо формату id.
Name
type
Type
string
Description
Тип завдання. Значення — creative-lab-lamp-prototype.
Name
name
Type
string
Description
Назва завдання, вказана під час його створення. Порожній рядок, якщо назву не було вказано.
Name
status
Type
string
Description
Статус завдання. Можливі значення: одне з PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Прогрес завдання. Якщо завдання ще не розпочато, це значення буде 0. Коли завдання успішно завершиться, воно стане 100.
Name
created_at
Type
timestamp
Description
Мітка часу створення завдання, у мілісекундах.
Мітка часу представляє кількість мілісекунд, що минули з 1 січня 1970 UTC, відповідно до стандарту RFC 3339. Наприклад, п'ятниця, 1 вересня 2023 12:00:00 PM GMT представлена як 1693569600000. Це стосується усіх міток часу в Meshy API.
Name
started_at
Type
timestamp
Description
Мітка часу початку виконання завдання, у мілісекундах. Якщо завдання ще не розпочато, це значення буде 0.
Name
finished_at
Type
timestamp
Description
Мітка часу завершення завдання, у мілісекундах. Якщо завдання ще не завершено, це значення буде 0.
Name
expires_at
Type
timestamp
Description
Мітка часу, коли термін дії результату завдання закінчується, у мілісекундах.
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 (кредити повертаються у разі невдачі).
Name
model_urls
Type
object
Description
URL-адреси для завантаження 3D-моделі, згенерованої з концептуального зображення. Присутнє, коли завдання успішно завершиться; {} до цього моменту.
- Name
  glb
  Type
  string
  Description
  URL-адреса для завантаження порожнистої матово-білої моделі абажура лампи у форматі GLB. Це модель, яку обробляє етап побудови.
Name
thumbnail_url
Type
string
Description
URL-адреса для завантаження відрендереного попереднього перегляду 3D-моделі. Порожній рядок, доки завдання не завершиться успішно.
Name
image_urls
Type
array of strings
Description
URL-адреси для завантаження кандидатів концептуальних зображень, згенерованих цим завданням прототипування. Наразі API завжди повертає рівно одного кандидата; це поле є масивом, щоб майбутні версії могли надавати кілька кандидатів без несумісних змін.

Example Lamp Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-lamp-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Об'єкт Lamp Build Task

Об'єкт Lamp Build Task — це одиниця роботи, яку Meshy відстежує для генерації фінального придатного до 3D-друку абажура лампи з успішного завдання-прототипу. Побудова запускає обробник лампи на 3D-моделі прототипу, щоб зробити її порожнистою, сплющити та відкрити нижню частину, а також (за наявності пресету кріплення) додати основу та кріплення для патрона.

Властивості

Name
id
Type
string
Description
Унікальний ідентифікатор завдання.
Name
type
Type
string
Description
Тип завдання. Значення — creative-lab-lamp-build.
Name
name
Type
string
Description
Назва завдання, надана під час його створення. Порожній рядок, якщо назву не було вказано.
Name
status
Type
string
Description
Статус завдання. Можливі значення: одне з PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Прогрес виконання завдання. Якщо завдання ще не розпочато, ця властивість дорівнює 0. Щойно завдання успішно завершиться, вона стане 100.
Name
created_at
Type
timestamp
Description
Мітка часу створення завдання, у мілісекундах.
Name
started_at
Type
timestamp
Description
Мітка часу початку виконання завдання, у мілісекундах.
Name
finished_at
Type
timestamp
Description
Мітка часу завершення завдання, у мілісекундах.
Name
expires_at
Type
timestamp
Description
Мітка часу закінчення терміну дії результату завдання, у мілісекундах.
Name
preceding_tasks
Type
integer
Description
Кількість завдань, що передують цьому. Має значення лише коли статус — PENDING.
Name
task_error
Type
object
Description
Деталі помилки для невдалих завдань. Див. Помилки для повного опису об'єкта task_error.
Name
consumed_credits
Type
integer
Description
Кількість кредитів, витрачених на це завдання. Повертає 0 для завдань зі статусом FAILED (кредити повертаються у разі невдачі).
Name
model_urls
Type
object
Description
URL-адреси для завантаження згенерованих артефактів, ключі — назви артефактів. Набір ключів залежить від output.format і options.light_source_preset:
- Name
  lamp_stl
  Type
  string
  Description
  URL-адреса для завантаження lamp.stl: абажур з відкритою нижньою частиною разом з основою, що містить отвір для кріплення, або суцільний закритий абажур, якщо options.light_source_preset мав значення none. Присутній, коли output.format мав значення stl (за замовчуванням).
- Name
  base_stl
  Type
  string
  Description
  URL-адреса для завантаження base.stl — кріплення для патрона джерела світла. Присутній, коли output.format мав значення stl і options.light_source_preset мав значення, відмінне від none. Відсутній, якщо пресет кріплення був none.
- Name
  bundle_zip
  Type
  string
  Description
  URL-адреса для завантаження zip-архіву з усіма артефактами, які створює обробник (lamp.stl, за наявності base.stl, а також — якщо options.include_result_json дорівнює true — result.json). Присутній, коли output.format мав значення zip. Якщо присутній bundle_zip, поля lamp_stl / base_stl відсутні.

Example Lamp Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-lamp-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "lamp_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/lamp.stl?Expires=***",
    "base_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/base.stl?Expires=***"
  }
}