Creative Lab — Keycap API

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

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

Ограничения: не менее 32 пикселей с каждой стороны, не более 178,956,970 пикселей в общей сложности и не более 20,000,000 байт после загрузки. Для Data URI ограничение применяется к декодированным байтам, поэтому сам исходный файл может быть до этого размера — это base64 текст, который примерно на треть больше, что важно для тела вашего запроса, но не для этого ограничения. Data URI должен объявлять тип содержимого image/* и ;base64.

Есть два способа предоставить изображение:

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

Необязательное имя задачи для отображения. Максимум 100 символов.

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

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

Запрос был неприемлем. Общие причины:

• Отсутствует параметр: image_url обязателен.
• Неверный формат изображения: Предоставленный image_url не является поддерживаемым форматом (.jpg, .jpeg, .png, .webp).
• Размеры изображения вне диапазона: Изображение слишком маленькое, превышает максимальный размер файла или превышает максимальное количество пикселей.
• Недоступный URL: image_url не может быть загружен (404 или timeout).
• Неверный Data URI: Строка base64 повреждена.
• Контент помечен: Входное изображение было помечено модерацией NSFW.

Аутентификация не удалась. Пожалуйста, проверьте ваш API-ключ.

Аккаунт находится на бесплатном плане (для создания задач требуется платный план) или недостаточно кредитов.

Входное изображение было помечено модерацией интеллектуальной собственности.

Вы превысили ваше ограничение частоты.

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

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

Прототипные задачи, созданные через веб-приложение, не принимаются — эндпоинт сборки принимает только прототипные задачи, произведенные POST /openapi/creative-lab/keycap/v1/prototype, и отклоняет любой другой источник с 404.

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

Необязательное имя задачи для отображения. Максимум 100 символов.

Основа кейкапа для сборки. В настоящее время доступно только значение cherry-mx-1x1-r1 — стандартный профиль Cherry MX 1u. Планируется добавить 3–5 дополнительных стандартных размеров; нестандартные размеры не поддерживаются.

Целевой размер скульптурной головы в миллиметрах: ее самая длинная сторона масштабируется до этого значения. Диапазон: [10, 40]. Значения выше примерно 32.9 могут быть уменьшены, чтобы голова все еще помещалась в защитный предел основания, поэтому доставленная самая длинная сторона может быть меньше запрошенной. Примененное значение сегодня не отображается в объекте задачи — если вам нужно подтвердить размер, который вы фактически получили, измерьте ограничивающий параллелепипед сетки keycap-head в загруженной модели.

Вертикальное смещение, применяемое к голове перед ее установкой на основание, в миллиметрах. Диапазон: [-5, 5].

Запрос был неприемлем. Общие причины:

• Отсутствует параметр: input_task_id и candidate_id обязательны.
• Недействительный UUID: input_task_id не является действительным UUID.
• Родитель не успешен: Указанная прототипная задача еще не достигла SUCCEEDED.
• Нет кандидатов: Прототипная задача была успешной, но не произвела кандидатов.
• Неизвестный кандидат: candidate_id не является одним из кандидатов входной задачи.
• Опции вне диапазона: Одно из полей options вышло за пределы допустимого диапазона или набора перечислений.

Аутентификация не удалась. Пожалуйста, проверьте ваш API-ключ.

Аккаунт находится на бесплатном плане (для создания задач требуется платный план) или имеет недостаточно кредитов.

Указанная прототипная задача не существует, принадлежит другому пользователю или была создана через веб-приложение (только прототипные задачи в режиме API переходят в сборку).

Вы превысили ваше ограничение частоты.

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

Уникальный идентификатор задачи keycap для получения.

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

Задача уже находится в конечном состоянии и не может быть отменена.

Задача не существует, принадлежит другому пользователю или ее стадия не соответствует пути URL.

Произошла неожиданная ошибка на стороне сервера при отмене. Задача могла быть или не быть отменена — перечитайте ее, чтобы подтвердить перед повторной попыткой.

Уникальный идентификатор для задачи keycap, которую нужно транслировать.

Либо prototype, либо build. Коллекция возвращает только задачи, этап которых соответствует URL — запрос /prototype никогда не возвращает задачи сборки и наоборот.

Номер страницы для пагинации.

Лимит размера страницы. Максимально допустимое значение — 100 элементов.

Поле для сортировки. Доступные значения:

• +created_at: Сортировка по времени создания в порядке возрастания.
• -created_at: Сортировка по времени создания в порядке убывания.

Уникальный идентификатор задачи. Хотя мы используем UUID с k-сортировкой для идентификаторов задач как деталь реализации, вы не должны делать никаких предположений о формате id.

Тип задачи. Значение — creative-lab-keycap-prototype.

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

Статус задачи. Возможные значения: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Прогресс задачи. Если задача еще не начата, это свойство будет 0. После успешного завершения задачи это значение станет 100.

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

Временная метка начала задачи в миллисекундах. Если задача еще не начата, это свойство будет 0.

Временная метка завершения задачи в миллисекундах. Если задача еще не завершена, это свойство будет 0.

Временная метка истечения результата задачи в миллисекундах.

Количество предшествующих задач.

Детали ошибки для неудавшихся задач. См. Ошибки для полной справки по объекту task_error.

Количество кредитов, потребленных этой задачей. Задача, достигшая SUCCEEDED, оплачивается полностью за свой этап. Задача, которая никогда не создается (ошибка 4xx во время запроса, включая отклонение модерации), не оплачивается вообще. Задача, достигшая FAILED, возвращает 0 — плата возвращается, включая асинхронную блокировку модерации. Отмена через DELETE возвращает средства только пока задача еще PENDING; задача, уже находящаяся в IN_PROGRESS, остается оплаченной, так как работа уже выполнена.

Скачиваемый URL рендера готового дизайна клавиши — как кандидат выглядит как готовая клавиша. Содержит одну запись; image_urls[i] соответствует candidate_ids[i]. Пусто, пока задача не достигнет SUCCEEDED. URL предназначен только для отображения; эндпоинт сборки использует candidate_ids, а не эти URL. Такой же жизненный цикл URL, как у model_urls: подписанный, без заголовка Authorization, действителен до expires_at и стабилен при повторном чтении задачи.

Непрозрачные идентификаторы кандидатов, параллельные image_urls. Передайте запись, соответствующую выбранному вами дизайну, как candidate_id запроса на сборку. Не делайте никаких предположений о формате этих идентификаторов.

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

Тип задачи. Значение — creative-lab-keycap-build.

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

Статус задачи. Возможные значения: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Прогресс задачи. Если задача еще не начата, это свойство будет 0. Как только задача будет выполнена, это значение станет 100.

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

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

Временная метка завершения задачи в миллисекундах.

Временная метка истечения результата задачи в миллисекундах.

Количество предшествующих задач. Имеет значение только когда статус PENDING.

Детали ошибки для неудавшихся задач. См. Ошибки для полной ссылки на объект task_error.

Количество кредитов, потребленных этой задачей. Задача, достигшая SUCCEEDED, оплачивается полностью за свой этап. Задача, которая никогда не создается (ошибка 4xx во время запроса, включая отклонение модерации), не оплачивается. Задача, достигшая FAILED, возвращает 0 — плата возвращается, включая асинхронную блокировку модерации. Отмена через DELETE возвращает средства только пока задача еще PENDING; задача, уже находящаяся в IN_PROGRESS, остается оплаченной, так как работа уже выполнена.

Скачиваемые URL для сгенерированных артефактов модели. И GLB, и OBJ пакет экспортируются в реальном масштабе миллиметров, Y-вверх, с передней частью клавиши, обращенной к +Z. Сетки называются keycap-head и keycap-base; когда основа возвращается к заполнению узором, третья сетка keycap-base-interior также присутствует для полости стержня. Не предполагайте наличие ровно двух сеток.

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

Скачиваемые URL для промежуточных изображений процесса, ключом является вид. Тот же жизненный цикл URL, что и у model_urls: подписанные, без заголовка Authorization, действительны до expires_at и стабильны при повторном чтении задачи. В настоящее время доступны виды:

• head_design — изображение дизайна выбранного кандидата, которое использовалось в сборке (всегда присутствует).
• composite — рендер отображения завершенной клавиши выбранного кандидата (присутствует, когда доступно).
• base_canvas — окрашенное полотно основы клавиши (присутствует, когда доступно).

Рассматривайте набор ключей как открытый; новые виды могут быть добавлены без нарушения совместимости.