Keycap API для Creative Lab

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

Изображение должно быть файлом JPG, JPEG, PNG или WebP размером не более 20 МБ (20 000 000 байт). Каждая сторона должна быть не менее 32 пикселей, а изображение может содержать не более 178 956 970 пикселей в целом. Изображение за пределами этих ограничений возвращает 400.

Meshy определяет формат по данным изображения, а не по расширению файла в URL. URL без расширения работает, и Meshy следует HTTP-редиректам. Meshy применяет ориентацию EXIF, поэтому повёрнутое фото с телефона отображается так, как оно выглядит на самом деле.

Data URI должен быть закодирован в base64 с указанием типа изображения, например data:image/png;base64,..., а декодированное изображение должно быть JPEG, PNG или WebP. Ограничение в 20 МБ применяется к декодированному изображению, поэтому текст base64 может быть примерно на треть больше.

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

Следует ли удалять фон с изображения прототипа. true возвращает прозрачный PNG в формате RGBA, так что вы можете разместить keycap на любом фоне. Если Meshy не может удалить фон, он возвращает изображение с его фоном, и задача всё равно завершается успешно.

Дизайн головки, который сборка превращает в 3D, сохраняет свой фон в любом случае. Сборка окрашивает основание keycap по изображению из image_urls, без фона, если вы передали true. Сборка возвращает это изображение как process_image_urls.composite.

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

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

Сообщение об ошибке указывает, какая именно проблема была обнаружена. Исправьте запрос и отправьте его снова.

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

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

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

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

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

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

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

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

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

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

Кандидат для сборки из массива candidate_ids задачи-прототипа. Значение, которого нет в этом массиве, возвращает 400.

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

Основание клавиши для сборки. Единственное значение — cherry-mx-1x1-r1, стандартная клавиша профиля Cherry MX 1u. Пользовательские размеры не поддерживаются, и любое другое значение возвращает 400.

Размер головки вдоль её самого длинного измерения, в миллиметрах, от 10 до 40. Meshy масштабирует головку так, чтобы её самое длинное измерение соответствовало этому значению. Значение вне диапазона возвращает 400.

Для значения выше примерно 32.9 Meshy может уменьшить размер, чтобы головка помещалась в пределах защитного контура основания. В этом случае головка может оказаться меньше, чем вы запросили. Объект задачи не возвращает размер, применённый Meshy. Чтобы проверить его, измерьте ограничивающий параллелепипед сетки keycap-head в модели.

Вертикальное смещение, применяемое к головке перед тем, как Meshy устанавливает её на основание, в миллиметрах, от -5 до 5. Значение вне диапазона возвращает 400.

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

• input_task_id отсутствует или не является действительным ID задачи.
• Статус задачи-прототипа не SUCCEEDED. Если она всё ещё выполняется, подождите и повторите попытку. Если она завершилась неудачей или была отменена, создайте новую задачу-прототип.
• Задача-прототип завершилась успешно, но не имеет кандидатов. Создайте новую задачу-прототип.
• candidate_id отсутствует или не входит в candidate_ids задачи-прототипа. Отправьте значение из этого массива.
• Поле в options вне допустимого диапазона, или base_model не является доступным значением.

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

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

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

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

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

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

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

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

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

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

id не является допустимым ID задачи. Укажите ID result из ответа на создание.

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

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

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

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

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

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

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

На стороне Meshy произошла ошибка сервера при отмене задачи, поэтому задача может быть как отменена, так и не отменена. Получите задачу, чтобы проверить её status, прежде чем повторить попытку.

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

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

Страница для возврата, от 1 до 255. 0 возвращает первую страницу. Значение вне диапазона от 0 до 255 возвращает 400.

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

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

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

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

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

Тип задачи, всегда creative-lab-keycap-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 не может прочитать списание, ответ при получении задачи или потоковой передаче не содержит это поле, а запрос списка возвращает 500. В этом случае повторите запрос.

URL-адреса для скачивания изображения готового колпачка клавиши. Массив содержит один URL после успешного завершения задачи и пуст до этого момента. image_urls[i] показывает кандидата из candidate_ids[i].

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

ID кандидатов, в том же порядке, что и image_urls. Чтобы собрать кандидата, отправьте его ID как candidate_id в запросе сборки. Не полагайтесь на формат этих ID.

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

Тип задачи, всегда creative-lab-keycap-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 не может определить сумму списания, поле отсутствует в ответе на запрос получения или потоковую передачу, а запрос списка возвращает 500. В этом случае повторите запрос.

URL-адреса для скачивания 3D-модели. Meshy экспортирует файл GLB и пакет OBJ в реальном масштабе в миллиметрах, с осью Y вверх, при этом передняя часть колпачка направлена вдоль +Z.

Модель содержит сетки с именами keycap-head и keycap-base. Когда Meshy использует запасной вариант с узорным заполнением для основания, модель также содержит сетку keycap-base-interior для полости штока. Не предполагайте, что модель содержит ровно две сетки.

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

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

Могут присутствовать следующие ключи:

• head_design: изображение дизайна выбранного кандидата, которое сборка преобразовала в 3D. Присутствует всегда.
• composite: изображение готового колпачка для выбранного кандидата, на основе которого было раскрашено основание. Может отсутствовать.
• base_canvas: раскрашенное основание колпачка. Может отсутствовать.

Meshy может добавлять ключи, поэтому игнорируйте неизвестный вам ключ.