Creative Lab — Collapsible Fidget API

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

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

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

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

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

Створіть модель складного fidget-предмета з вихідного фото. Дивіться Об'єкт завдання Collapsible Fidget для ознайомлення з форматом відповіді.

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

Параметри

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

Повертає

Властивість result відповіді містить id щойно створеного завдання Collapsible Fidget. Опитуйте кінцеву точку Отримати завдання або підпишіться на потік, поки завдання не досягне статусу 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.cn/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.cn/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.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.cn/***/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.cn/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

Стрімінг завдання зі створення складного фіджета

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

Параметри

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

Повертає

Повертає потік об'єктів завдання Collapsible Fidget у формі Server-Sent Events. Для завдань зі статусом PENDING або IN_PROGRESS потік відповіді включатиме лише необхідні поля progress та status.

Request

GET

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

curl -N https://api.meshy.cn/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.
// 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",
  "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.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.cn/***/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.cn/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.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
    }
  }
]

Об'єкт завдання Collapsible Fidget Task

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

Властивості

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.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}