Creative Lab Collapsible Fidget API

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

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

На відміну від інших endpoint'ів Creative Lab, цей не має окремих етапів прототипу та побудови. Тут немає зображень-кандидатів для вибору, тому одне завдання перетворює фотографію на 3D-модель.

У запиті також немає налаштувань геометрії. Веб-застосунок дозволяє встановлювати розмір, кількість шарів, ширину проміжку, товщину стінки, глибину екструзії та опуклість. Кожне завдання API використовує для них однакові значення за замовчуванням.

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

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

Генерує складану модель fidget із фотографії. Про поля задачі див. Об'єкт задачі Collapsible Fidget.

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

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

Параметри

Name
image_url
Type
string
Обов'язковий
Description
Фотографія, яку потрібно перетворити на складаний fidget, у вигляді публічного URL або data URI (data:image/jpeg;base64,<your base64-encoded image data>).
Зображення має бути файлом JPG, JPEG, PNG або WebP розміром не більше 20 МБ.
Силует об'єкта стає кільцями, тому найкраще підходить об'єкт з одним чітким, замкненим контуром. Перевантажений фон, кілька окремих об'єктів або дуже тонкі форми можуть залишити занадто мало площі для вкладених стінок. У такому разі задача завершується невдачею.
Name
name
Type
string
Description
Назва задачі, до 100 символів. Вона повертається в полі name задачі, і Meshy не гравірує її на моделі. Довша назва поверне 400.

Результати

Поле result містить ID нової задачі. Отримайте задачу або транслюйте її, доки status не стане SUCCEEDED. Потім завантажте файл STL, придатний для друку, з model_urls.stl. Щоб спочатку переглянути модель, завантажте файл GLB з model_urls.glb, коли він наявний.

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

Name
400 - Bad Request
Description
Запит не може виконатися. Наприклад:
- Відсутнє image_url.
- Зображення не є файлом JPG, JPEG, PNG або WebP.
- Зображення занадто мале, перевищує 20 МБ або максимальну кількість пікселів.
- Meshy не може завантажити зображення, наприклад через те, що URL повертає 404 або час очікування вичерпано.
- Data URI не є дійсним base64.
- Зображення позначено як NSFW.
Повідомлення про помилку вказує, яку проблему виявлено. Виправте запит і надішліть його знову.
Name
401 - Unauthorized
Description
API-ключ відсутній або недійсний. Перевірте заголовок Authorization.
Name
402 - Payment Required
Description
Застосовується одне з наведеного:
- На рахунку недостатньо кредитів.
- API-ключ, робоча область або учасник досягли ліміту кредитів.
- Обліковий запис перебуває на безкоштовному плані.
Перевірте свої кредити та план, потім повторіть спробу.
Name
403 - Forbidden
Description
У вашій команді увімкнено IP Filtering, і Meshy позначив зображення як таке, що стосується інтелектуальної власності третіх осіб. Надішліть зображення, на використання якого ви маєте права.
Name
429 - Too Many Requests
Description
Досягнуто одного з таких обмежень:
- Ви надіслали більше запитів, ніж дозволяє ваше обмеження частоти. Зачекайте кілька секунд, потім повторіть спробу. Див. Обмеження частоти.
- Занадто багато ваших задач перебувають у черзі або виконуються. Зачекайте, поки частина з них завершиться, потім повторіть спробу.
- На необмеженому плані без кредитів ви досягли кількості задач, які можуть виконуватися без кредитів. Зачекайте завершення задачі або додайте кредити.
Name
500 - Internal Server Error
Description
У Meshy сталася помилка сервера, наприклад через неможливість виконати перевірку інтелектуальної власності для зображення. Meshy не створює задачу та повертає будь-які стягнуті кредити. Повторіть запит.

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

Отримати задачу Collapsible Fidget

Повертає задачу Collapsible Fidget. Повертаються лише задачі, створені через цю кінцеву точку. Задача з іншої кінцевої точки Creative Lab або створена у веб-застосунку, поверне 404.

Опис полів див. у Об'єкт задачі 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=***"
  }
}

Параметри

Name
id
Type
path
Description
ID задачі з відповіді на створення.

Повертає

Об'єкт задачі Collapsible Fidget.

Режими збою

Name
400 - Bad Request
Description
id не є дійсним ID задачі. Надішліть ID result з відповіді на створення.
Name
403 - Forbidden
Description
У вашій команді увімкнено IP Filtering, і Meshy позначив зображення задачі як таке, що порушує права інтелектуальної власності третіх осіб. Команди на плані Enterprise не отримують цю помилку. Створіть задачу із зображення, на використання якого у вас є права.
Name
404 - Not Found
Description
Жодна задача Collapsible Fidget з цим ID не належить вашому акаунту, або задачу не було створено через цю кінцеву точку. Перевірте ID.
Name
500 - Internal Server Error
Description
Meshy не вдалося виконати перевірку на інтелектуальну власність. Повторіть запит.

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

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

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

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).

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

Name
id
Type
path
Description
ID завдання, яке потрібно скасувати.

Повертає

204 No Content з порожнім тілом.

Випадки помилок

Name
400 - Bad Request
Description
Застосовується одне з наступного:
- id не є дійсним ID завдання. Надішліть ID result з відповіді на створення.
- Завдання вже має остаточний статус (SUCCEEDED, FAILED або CANCELED), тому його не можна скасувати.
Name
404 - Not Found
Description
Жодне завдання Collapsible Fidget з таким ID не належить вашому акаунту, або завдання не було створено за допомогою цієї кінцевої точки. Перевірте ID.

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

Транслювати потокові оновлення завдання Collapsible Fidget

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

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 following PENDING frame is shortened 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=***"
  }
}

Параметри

Name
id
Type
path
Description
ID завдання з відповіді на створення.

Повертає

Потік об'єктів завдання Collapsible Fidget. Кожна подія містить повний об'єкт завдання, так само як його повертає Отримати завдання Collapsible Fidget. Поки завдання має статус PENDING або IN_PROGRESS, його вихідні поля досі порожні (null, [] або {}), а finished_at має значення null.

Якщо IP Filtering блокує результат завдання, потік надсилає замість нього одну подію error з тим status_code, який повернув би GET-запит.

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

Список завдань Collapsible Fidget

Повертає ваші завдання 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=***"
    }
  }
]

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

Name
page_num
Type
integer
за замовчуванням 1
Description
Сторінка, яку потрібно повернути, від 1 до 255. 0 повертає першу сторінку. Значення поза межами 0–255 повертає 400.
Name
page_size
Type
integer
за замовчуванням 10
Description
Кількість завдань на сторінці, до 100. Значення від 101 до 255 повертає 100 завдань, а 0 використовує значення за замовчуванням. Значення поза межами 0–255 повертає 400.
Name
sort_by
Type
string
за замовчуванням -created_at
Description
Порядок сортування.
Доступні значення:
- -created_at: спочатку найновіші
- +created_at: спочатку найстаріші

Повертає

Масив об'єктів завдання Collapsible Fidget.

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

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

Властивості

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=***"
  }
}

Name
id
Type
string
Description
ID завдання. Не покладайтеся на його формат.
Name
type
Type
string
Description
Тип завдання, завжди creative-lab-fidget-collapsible.
Name
name
Type
string
Description
name, яке ви надіслали під час створення завдання, або "", якщо ви його не надсилали.
Name
status
Type
string
Description
Статус завдання.
Доступні значення:
- PENDING: очікує в черзі
- IN_PROGRESS: генерується результат
- SUCCEEDED: завершено, з результатом
- FAILED: завершено, з причиною в task_error
- CANCELED: завершено, без результату
Name
progress
Type
integer
Description
Відсоток виконаної роботи, від 0 до 100. Дорівнює 0, доки завдання не почнеться, і 100, коли воно завершується успішно.
Name
created_at
Type
timestamp
Description
Час створення завдання, у мілісекундах Unix.
Name
started_at
Type
timestamp
Description
Час, коли воркер розпочав завдання, у мілісекундах Unix. До цього моменту — null.
Name
finished_at
Type
timestamp
Description
Час, коли завдання досягло кінцевого статусу, у мілісекундах Unix. До цього моменту — null.
Name
expires_at
Type
timestamp
Description
Час, коли результат завдання спливає, у мілісекундах Unix. Це 3 дні після finished_at, або 3 дні після created_at, доки завдання не завершиться. Для облікових записів Enterprise, які зберігають результати API необмежено довго, це приблизно на 100 років пізніше. Див. Зберігання ресурсів.
Name
preceding_tasks
Type
integer
Description
Позиція завдання в черзі, доки воно має статус PENDING. 1 означає, що воно виконається наступним. 0 — після того, як завдання покидає чергу, і завжди 0 у результатах списку.
Name
task_error
Type
object
Description
Причина, чому завдання завершилося невдало. null, якщо тільки status не дорівнює FAILED. Див. Помилки.
Name
consumed_credits
Type
integer
Description
Кількість кредитів, списаних за завдання, після будь-якого повернення. Запит, що повертає помилку, не оплачується. Невдале завдання має значення 0, оскільки Meshy повертає за нього кредити. Скасування повертає кредити за завдання лише доки воно має статус PENDING. Якщо Meshy не може прочитати інформацію про списання, відповідь get або stream не міститиме це поле, а запит списку поверне 500. У такому разі повторіть запит.
Name
model_urls
Type
object
Description
URL-адреси для завантаження 3D-моделі, порожні, доки завдання не завершиться успішно. Успішно завершене завдання завжди має stl, і має glb лише якщо Meshy відрендерив попередній перегляд.
- Name
  stl
  Type
  string
  Description
  URL-адреса для завантаження файлу STL, який і є файлом для друку. Ви можете відкрити його безпосередньо в слайсері.
- Name
  glb
  Type
  string
  Description
  URL-адреса для завантаження файлу GLB для попереднього перегляду моделі в 3D-переглядачі. Його кольори призначені лише для попереднього перегляду. Файл STL не має кольору, тому надрукований фіджет набуває кольору від філаменту.
  Якщо Meshy не може відрендерити попередній перегляд, model_urls не міститиме ключ glb, тому перевіряйте наявність ключа перед тим, як його читати. Завдання зі статусом SUCCEEDED завжди має stl.