Creative Lab Fidget Pixel API

Фотография для преобразования в пиксель-арт — в виде публичного URL или Data URI (data:image/jpeg;base64,<ваши данные изображения в кодировке base64>).

Изображение должно быть файлом JPG, JPEG, PNG или WebP размером не более 20 МБ. Meshy определяет формат по данным изображения, а не по расширению файла в URL. URL без расширения тоже подходит, и Meshy следует по перенаправлениям (redirects).

Что изображено на фотографии — определяет стиль пиксель-арта. Эти два стиля заметно отличаются друг от друга. Любое другое значение вернёт 400.

Допустимые значения:

• person: человек на портретном или полноростовом фото. Meshy рисует пиксельный спрайт в стиле чиби.
• other: любой другой объект, например питомец, предмет, маскот, логотип или пейзаж. Meshy рисует пиксельную иконку в стиле бисерной мозаики.

Название задачи, до 100 символов. Оно возвращается в поле name задачи. При превышении длины возвращается 400.

Запрос не может быть выполнен. Например:

• Отсутствует image_url или type.
• type не равен person или other.
• Изображение не является файлом JPG, JPEG, PNG или WebP.
• Изображение слишком маленькое, превышает 20 МБ или превышает максимальное количество пикселей.
• Meshy не может загрузить изображение, например потому что URL возвращает 404 или истекло время ожидания.
• Data URI не является корректным base64.
• Изображение было помечено как NSFW.

В сообщении об ошибке указано, в чём проблема. Исправьте запрос и отправьте его снова.

API-ключ отсутствует или недействителен. Проверьте заголовок Authorization.

Применимо одно из следующего:

• На счёте недостаточно кредитов.
• API-ключ, рабочая область или участник достигли лимита кредитов.
• Аккаунт использует бесплатный тарифный план.

Проверьте количество кредитов и тарифный план, затем повторите попытку.

В вашей команде включена функция IP Filtering, и Meshy пометила изображение как содержащее стороннюю интеллектуальную собственность. Отправьте изображение, на использование которого у вас есть права.

Достигнут один из следующих лимитов:

• Вы отправили больше запросов, чем допускает ограничение частоты. Подождите несколько секунд и повторите попытку. См. Ограничения частоты.
• Слишком много ваших задач находятся в очереди или выполняются. Дождитесь завершения части из них, затем повторите попытку.
• На безлимитном тарифном плане без оставшихся кредитов вы достигли количества задач, которые могут выполняться без кредитов. Дождитесь завершения задачи или пополните баланс кредитов.

Meshy столкнулась с серверной ошибкой, например из-за невозможности выполнить проверку изображения на интеллектуальную собственность. Meshy не создаёт задачу и возвращает все списанные кредиты. Повторите запрос.

ID задачи создания прототипа, которую нужно собрать. Это должна быть задача, созданная вашим аккаунтом с помощью POST /openapi/creative-lab/fidget-pixel/v1/prototype, со статусом SUCCEEDED.

ID, не являющийся одной из ваших задач создания прототипа Fidget Pixel через API, возвращает 404, включая прототип, созданный в веб-приложении.

Название задачи, до 100 символов. Оно возвращается в поле name задачи. Более длинное название возвращает 400.

Форма основания каждой детали. Любое другое значение возвращает 400.

Доступные значения:

• square: квадратные детали на квадратной сетке
• hex: шестиугольные детали на шестиугольной сетке, со значением piece_size_mm, равным 6 или 8

Количество ячеек сетки вдоль каждой стороны доски, 16 или 32. Любое другое значение возвращает 400. Сетка 32 сохраняет больше деталей. Сетка 16 даёт меньше деталей того же размера, поэтому доска получается примерно вдвое уже.

Длина стороны каждой детали в миллиметрах: 6, 8 или 10. Любое другое значение возвращает 400. Вместе с grid_size определяет размер печатаемой доски. Например, сетка 32 из деталей 8 мм имеет размер около 26,5 см с каждой стороны.

10 не работает с hex и возвращает 400, поскольку наклонная грань шестиугольника создаёт нависание на большинстве потребительских FDM-принтеров.

Максимальное количество цветов в палитре пиксель-арта, от 1 до 8. Значение вне диапазона возвращает 400. Для печати вам потребуется до color_count плюс один филамент: по одному на цвет и один для серых корпусов.

Высота каждой детали в миллиметрах, от 10 до 80. Значение вне диапазона возвращает 400.

Формат файла результата. Любое другое значение возвращает 400.

Доступные значения:

• 3mf: один многоцветный файл model.3mf, возвращаемый в model_urls.3mf

Запрос не может быть выполнен. Например:

• input_task_id отсутствует или не является допустимым ID задачи.
• Статус задачи создания прототипа не SUCCEEDED. Если она ещё выполняется, подождите и повторите попытку. Если она завершилась неудачей или была отменена, создайте новую задачу создания прототипа.
• Задача создания прототипа завершилась успешно, но не содержит изображения. Создайте новую задачу создания прототипа.
• Поле options выходит за пределы допустимых значений, например grid_size, отличное от 16 или 32.
• piece_size_mm равно 10, а shape — hex. Шестиугольные детали бывают только 6 и 8 мм.
• output.format не равно 3mf.

Сообщение об ошибке указывает, в чём именно проблема.

API-ключ отсутствует или недействителен. Проверьте заголовок Authorization.

Применимо одно из следующего:

• На аккаунте недостаточно кредитов.
• API-ключ, рабочая область или участник достигли лимита кредитов.
• Аккаунт находится на бесплатном плане.

Проверьте количество кредитов и план, затем повторите попытку.

В вашей команде включена функция IP Filtering, и Meshy пометила изображение задачи создания прототипа как содержащее стороннюю интеллектуальную собственность. Создайте задачу создания прототипа из изображения, на использование которого у вас есть права.

input_task_id не соответствует ни одной задаче создания прототипа Fidget Pixel, созданной вашим аккаунтом через API. Прототип, созданный в веб-приложении, также возвращает 404. Отправьте ID из поля result ответа на создание прототипа.

Достигнуто одно из следующих ограничений:

• Вы отправили больше запросов, чем допускает ваше ограничение частоты. Подождите несколько секунд и повторите попытку. См. Ограничения частоты.
• Слишком много ваших задач находится в очереди или выполняется. Дождитесь завершения части из них и повторите попытку.
• На безлимитном плане без оставшихся кредитов вы достигли количества задач, которые могут выполняться без кредитов. Дождитесь завершения задачи или пополните кредиты.

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

ID задачи из ответа на создание.

id не является допустимым ID задачи. Отправьте ID result из ответа на создание.

В вашей команде включена функция IP Filtering, и Meshy пометил изображение задачи прототипа как нарушающее права интеллектуальной собственности третьих лиц. Для задач сборки и команд на плане Enterprise эта ошибка не возникает. Создайте задачу прототипа на основе изображения, на использование которого у вас есть права.

Задача Fidget Pixel с таким ID не принадлежит вашему аккаунту, либо этап задачи не соответствует пути. Проверьте ID и используйте /prototype или /build в соответствии с задачей.

Meshy не удалось выполнить проверку интеллектуальной собственности. Повторите запрос.

ID задачи, которую нужно отменить.

Применимо одно из следующего:

• id не является допустимым ID задачи. Отправьте ID result из ответа на создание.
• Задача уже имеет окончательный статус (SUCCEEDED, FAILED или CANCELED), поэтому её нельзя отменить.

Задача Fidget Pixel с таким ID не принадлежит вашему аккаунту, либо стадия задачи не соответствует пути. Проверьте ID и используйте /prototype или /build в соответствии с задачей.

ID задачи из ответа на создание.

Этап для вывода списка: prototype или build.

Возвращаемая страница, от 1 до 255. 0 возвращает первую страницу. Значение за пределами диапазона 0–255 приводит к ошибке 400.

Количество задач на странице, до 100. Значение от 101 до 255 возвращает 100 задач, а 0 использует значение по умолчанию. Значение за пределами диапазона 0–255 приводит к ошибке 400.

Порядок сортировки.

Доступные значения:

• -created_at: сначала новые
• +created_at: сначала старые

ID задачи. Не полагайтесь на его формат.

Тип задачи, всегда creative-lab-fidget-pixel-prototype.

Значение name, отправленное при создании задачи, или "", если вы его не отправляли.

Статус задачи.

Доступные значения:

• PENDING: ожидание в очереди
• IN_PROGRESS: генерация результата
• SUCCEEDED: финальный статус, с результатом
• FAILED: финальный статус, с причиной в task_error
• CANCELED: финальный статус, без результата

Процент выполненной работы, от 0 до 100. Равен 0 до начала выполнения задачи и 100, когда она завершается успешно.

Время создания задачи, в миллисекундах Unix.

Время, когда обработчик начал выполнение задачи, в миллисекундах Unix. До этого момента — null.

Время, когда задача достигла финального статуса, в миллисекундах Unix. До этого момента — null.

Время истечения срока действия результата задачи, в миллисекундах Unix. Это 3 дня после finished_at, либо 3 дня после created_at, пока задача не завершена. Для аккаунтов Enterprise, которые хранят результаты API бессрочно, это значение указывает примерно на 100 лет вперёд. См. Хранение ресурсов.

Позиция задачи в очереди, пока она находится в статусе PENDING. 1 означает, что она будет обработана следующей. После выхода задачи из очереди — 0, и в результатах списка всегда 0.

Причина сбоя задачи. null, если status не равен FAILED. См. Ошибки.

Количество кредитов, списанных за задачу, с учётом любого возврата. За запрос, вернувший ошибку, плата не взимается. Для неудавшейся задачи значение равно 0, так как Meshy возвращает средства. Отмена задачи возвращает средства только пока она находится в статусе PENDING. Если Meshy не может определить сумму списания, поле отсутствует в ответе get или stream, а запрос списка возвращает 500. В этом случае повторите запрос.

URL-адреса для скачивания изображения в стиле пиксель-арт. Массив содержит один URL после успешного завершения задачи, а до этого он пуст.

URL-адреса подписаны, поэтому запрашивайте их без заголовка Authorization. Они остаются действительными до expires_at. Повторное получение задачи до этого момента возвращает те же URL-адреса, а не заново подписанные. Срок действия истёкшего URL нельзя продлить, поэтому скачайте и сохраните файлы заранее.

ID задачи. Не полагайтесь на его формат.

Тип задачи, всегда creative-lab-fidget-pixel-build.

Значение name, которое вы отправили при создании задачи, или "", если вы его не отправляли.

Статус задачи.

Доступные значения:

• PENDING: ожидание в очереди
• IN_PROGRESS: генерация результата
• SUCCEEDED: завершено, с результатом
• FAILED: завершено, с причиной в task_error
• CANCELED: завершено, без результата

Процент выполненной работы, от 0 до 100. Равен 0, пока задача не начата, и 100, когда она успешно завершена.

Время создания задачи, в миллисекундах Unix.

Время, когда воркер начал выполнение задачи, в миллисекундах Unix. До этого момента — null.

Время, когда задача достигла финального статуса, в миллисекундах Unix. До этого момента — null.

Время истечения срока действия результата задачи, в миллисекундах Unix. Это 3 дня после finished_at, либо 3 дня после created_at, пока задача не завершена. Для корпоративных аккаунтов (Enterprise), которые хранят результаты API бессрочно, это значение указывает примерно на 100 лет вперёд. См. Хранение ресурсов.

Позиция задачи в очереди, пока она находится в статусе PENDING. 1 означает, что она начнётся следующей. 0 после того, как задача покидает очередь, и всегда 0 в результатах списка.

Причина сбоя задачи. null, если status не равен FAILED. См. Ошибки.

Количество кредитов, списанных за задачу, с учётом возможного возврата. Запрос, вернувший ошибку, не оплачивается. Для неудавшейся задачи значение равно 0, так как Meshy возвращает кредиты. Отмена возвращает кредиты за задачу только пока она находится в статусе PENDING. Если Meshy не может определить сумму списания, в ответе на get-запрос или поток это поле отсутствует, а запрос списка возвращает 500. В этом случае повторите запрос.

URL-адреса для скачивания результата, с ключами по формату файла. Объект содержит одну запись — для формата output.format, который вы отправили, и остаётся пустым до завершения задачи.

URL-адреса подписаны, поэтому запрашивайте их без заголовка Authorization. Они остаются действительными до expires_at. Повторное получение задачи до этого момента возвращает те же URL-адреса, а не вновь подписанные. Истёкший URL-адрес нельзя обновить, поэтому скачивайте и сохраняйте файлы до истечения срока.