Creative Lab — API складаної фіджет-іграшки

Перетворіть вихідне фото на складану фіджет-іграшку, надруковану одразу в зібраному вигляді: силует об'єкта перетворюється на набір вкладених концентричних кілець, які складаються плоско та знову розтягуються, надрукованих одним цілим без збирання.

POST /openapi/creative-lab/fidget-collapsible/v1

На відміну від інших endpoint Creative Lab, цей не має пари етапів прототип/збірка — тут немає проміжних кандидатів для вибору, тож одне завдання проводить зображення одразу до 3D-моделі. Елементи керування геометрією, які надає веб-застосунок (розмір, кількість шарів, ширина проміжку, товщина стінки, глибина екструзії, випуклість), також не є частиною запиту: кожне завдання будується з однаковими стандартними параметрами на боці сервера.

POST/openapi/creative-lab/fidget-collapsible/v1

Створення завдання Collapsible Fidget

Згенеруйте модель складного фіджета (collapsible fidget) з вихідного фото. Дивіться The Collapsible Fidget Task Object щодо структури відповіді.

Кожне завдання коштує 6 кредитів і потребує платного плану.

Параметри

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

Результат

Властивість result у відповіді містить id завдання щойно створеного завдання складного фіджета. Опитуйте кінцеву точку Get a Task або підпишіться на stream, доки завдання не досягне статусу SUCCEEDED, а потім завантажте придатний для друку STL за посиланням model_urls.stl (а також, якщо наявний, GLB за посиланням model_urls.glb для попереднього перегляду).

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

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

Request

POST

/openapi/creative-lab/fidget-collapsible/v1

curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1 \
  -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>"
  }'

Response

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

GET/openapi/creative-lab/fidget-collapsible/v1/:id

Отримати завдання Collapsible Fidget

Отримайте завдання collapsible fidget за дійсним id завдання. Тут доступні лише завдання, створені через цю кінцеву точку — завдання з іншої кінцевої точки Creative Lab, або створене у веб-застосунку, повертає 404.

Дивіться Об'єкт завдання Collapsible Fidget щодо форми відповіді.

Параметри

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

Повертає

Відповідь містить об'єкт завдання collapsible fidget.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

DELETE/openapi/creative-lab/fidget-collapsible/v1/:id

Видалити завдання Collapsible Fidget

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

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

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

Повертає

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

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

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

Request

DELETE

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

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

GET/openapi/creative-lab/fidget-collapsible/v1/:id/stream

Стрімінг завдання Collapsible Fidget

Отримуйте оновлення в реальному часі для завдання Collapsible Fidget через Server-Sent Events (SSE). Якщо завдання не існує або не було створено через цю кінцеву точку, надсилається одна корисне навантаження event: error зі status_code: 404, після чого потік закривається.

Параметри

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

Повертає

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

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream

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

Response Stream

// Error event example (task not found, or not created through this endpoint)
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": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

GET/openapi/creative-lab/fidget-collapsible/v1

Отримати список завдань Collapsible Fidget

Отримайте пагінований список ваших завдань collapsible fidget. Включаються лише завдання, створені через цю кінцеву точку.

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

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: Сортування за часом створення у спадному порядку.

Повертає

Повертає пагінований список об'єктів завдання collapsible fidget.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-fidget-collapsible",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123512000,
    "expires_at": 1729382712000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
    }
  }
]

Об'єкт завдання складного фіджета (Collapsible Fidget Task)

Об'єкт Collapsible Fidget Task — це робоча одиниця, яку Meshy відстежує для перетворення вихідного фото на придатну для 3D-друку без збірки складну модель фіджета. Це одноетапне завдання: тут немає прототипу, від якого можна було б відштовхуватися в ланцюжку, а проміжний силует не є частиною відповіді.

Властивості

Name
id
Type
string
Description
Унікальний ідентифікатор завдання. Хоча як деталь реалізації ми використовуємо k-сортований UUID для ідентифікаторів завдань, вам не слід робити жодних припущень щодо формату id.
Name
type
Type
string
Description
Тип завдання. Значення — creative-lab-fidget-collapsible.
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 за Гринвічем представлена як 1693569600000. Це стосується усіх міток часу в Meshy API.
Name
started_at
Type
timestamp
Description
Мітка часу початку виконання завдання, у мілісекундах. Якщо завдання ще не розпочато, це значення буде null.
Name
finished_at
Type
timestamp
Description
Мітка часу завершення завдання, у мілісекундах. Якщо завдання ще не завершено, це значення буде null.
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-моделі. Заповнюється, щойно завдання отримає статус SUCCEEDED: stl присутній завжди, glb — лише якщо рендеринг попереднього перегляду завершився успішно.
- Name
  stl
  Type
  string
  Description
  URL-адреса для завантаження файлу STL. Це кінцевий результат, придатний для друку — надішліть його одразу до слайсера.
- Name
  glb
  Type
  string
  Description
  URL-адреса для завантаження файлу GLB, для попереднього перегляду моделі у 3D-переглядачі. Його кольори призначені лише для попереднього перегляду: STL не містить кольору, а надрукований фіджет отримує колір від філаменту. GLB надається за принципом «найкраще можливе»: коли рендер попереднього перегляду недоступний, ключ повністю вилучається з model_urls, тому зчитуйте це значення обережно — stl є кінцевим результатом і завжди присутній у завданні зі статусом SUCCEEDED.

Example Collapsible Fidget Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}