Creative Lab — Collapsible Fidget API

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

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

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

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

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

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

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

Параметры

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

    Исходная фотография, из которой Meshy создаст складной фиджет. В настоящее время поддерживаются форматы .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 только что созданной задачи складного фиджета. Опрашивайте эндпоинт Получить задачу или подпишитесь на поток, пока задача не достигнет статуса 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.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

Получить задачу складного фиджета

Получите задачу складного фиджета по действительному 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.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

Delete a Collapsible Fidget Task

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

Path Parameters

  • Name
    id
    Type
    path
    Description

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

Returns

Возвращает 204 No Content при успехе с пустым телом ответа.

Failure Modes

  • 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 отслеживает для превращения исходной фотографии в печатаемую сразу в собранном виде складную антистресс-модель. Это одноэтапная задача: здесь нет прототипа, от которого можно было бы выстроить цепочку, а промежуточный силуэт не входит в состав ответа.

Свойства

  • Name
    id
    Type
    string
    Description

    Уникальный идентификатор задачи. Хотя в качестве деталей реализации мы используем k-sortable 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=***"
  }
}