lowpoly будет отключён 30 окт. 2026 г.. Перейдите на другую модель до этих дат, чтобы избежать ошибок в запросах.

Creative Lab — Collapsible Fidget API

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

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

В отличие от других endpoint'ов Creative Lab, у этого нет пары этапов прототип/финальная сборка — здесь нет промежуточных вариантов, между которыми нужно выбирать, поэтому одна задача проводит изображение через весь путь до 3D-модели. Элементы управления геометрией, доступные в веб-приложении (размер, количество слоёв, ширина зазора, толщина стенки, глубина выдавливания, выпуклость), также не являются частью запроса: каждая задача собирается с одинаковыми серверными настройками по умолчанию.

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

Создание задачи складного фиджета

Сгенерируйте модель складного фиджета из исходной фотографии. Информацию о структуре ответа см. в разделе Объект задачи складного фиджета.

Каждая задача стоит 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 задачи вновь созданной задачи складного фиджета. Опрашивайте эндпоинт Получить задачу или подпишитесь на поток, пока задача не достигнет статуса 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 некорректна.
    • Контент отмечен модерацией: входное изображение было отмечено NSFW-модерацией (moderation).
  • 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)

Получите задачу складного непоседы по действительному id задачи. Здесь доступны только задачи, созданные через этот эндпоинт — задача из другого эндпоинта Creative Lab или задача, созданная в веб-приложении, вернёт 404.

Информацию о структуре ответа см. в разделе Объект задачи складного непоседы.

Параметры

  • Name
    id
    Type
    path
    Description

    Уникальный идентификатор задачи складного непоседы, которую нужно получить.

Возвращаемые данные

Ответ содержит объект задачи складного непоседы.

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

Delete a Collapsible Fidget Task

Отменить задачу складного фиджета. Если задача всё ещё находится в статусе PENDING, кредиты, израсходованные при создании, возвращаются. Задачи, которые уже находятся в статусе IN_PROGRESS, отменяются без возврата средств (воркер может уже расходовать ресурсы). Задачи, которые уже достигли терминального состояния (SUCCEEDED, FAILED, CANCELED), не могут быть отменены.

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

  • Name
    id
    Type
    path
    Description

    Уникальный идентификатор задачи складного фиджета, которую нужно отменить.

Возвращает

Возвращает 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=***"
    }
  }
]

Объект задачи складного фиджета

Объект задачи складного фиджета — это единица работы, за которой следит 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

    Ссылки для скачивания сгенерированной 3D-модели. Заполняется после того, как задача получит статус SUCCEEDED: stl присутствует всегда, glb — только если предпросмотровый рендер выполнен успешно.

    • Name
      stl
      Type
      string
      Description

      Ссылка для скачивания файла STL. Это результат, пригодный для печати, — отправляйте его напрямую в слайсер.

    • Name
      glb
      Type
      string
      Description

      Ссылка для скачивания файла 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=***"
  }
}