API складного фиджета Creative Lab

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

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

В отличие от других endpoint'ов Creative Lab, у этого нет отдельных этапов prototype и build. Нет изображений-кандидатов для выбора, поэтому одна задача сразу превращает фото в 3D-модель.

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

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

Создание задачи Collapsible Fidget

Создаёт модель складного фиджета (collapsible 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
Фотография, которую нужно превратить в складной фиджет, в виде публичного URL или Data URI (data:image/jpeg;base64,<ваши закодированные в base64 данные изображения>).
Изображение должно быть файлом JPG, JPEG, PNG или WebP размером не более 20 МБ.
Силуэт объекта становится кольцами, поэтому лучше всего подходит объект с одним чётким, замкнутым контуром. Загруженный фон, несколько отдельных объектов или очень тонкие формы могут оставить слишком мало площади для вложенных стенок. В этом случае задача завершается ошибкой.
Name
name
Type
string
Description
Название задачи, до 100 символов. Оно возвращается в поле name задачи, и Meshy не наносит его на модель в виде гравировки. Более длинное название приводит к ошибке 400.

Возвращаемые значения

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