Creative Lab — Collapsible Fidget API

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

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

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

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

Create a Collapsible Fidget Task

Создайте модель складного непоседы (fidget) из исходной фотографии. Обратитесь к разделу The Collapsible Fidget Task Object для описания формата ответа.

Каждая задача стоит 6 кредитов и требует платного тарифного плана.

Параметры

  • Name
    image_url
    Type
    string
    Обязательный
    Description

    Исходное фото, из которого Meshy создаст складного непоседу. В настоящее время поддерживаются форматы .jpg, .jpeg, .png и .webp.

    Изображение можно предоставить двумя способами:

    • Общедоступный URL: URL, доступный из публичного интернета.
    • Data URI: изображение, закодированное в base64. Пример data URI: data:image/jpeg;base64,<your base64-encoded image data>.

    Лучше всего подходит объект с одним чётким, замкнутым контуром — именно силуэт становится кольцами. Загруженный фон, несколько отдельных объектов или слишком тонкие формы могут оставить слишком мало площади для вложенных стенок, и задача завершится ошибкой.

  • 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 повреждена.
    • Контент помечен: исходное изображение было помечено системой 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=***"
  }
}