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,<ваши закодированные в base64 данные изображения>.

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

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

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

Запрос был некорректен. Распространённые причины:

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

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

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

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

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

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

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

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

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

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

Основание keycap, на котором выполняется сборка. В настоящее время единственное доступное значение — cherry-mx-1x1-r1 — стандартный keycap профиля 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 вышло за пределы допустимого диапазона или набора значений enum.

Ошибка аутентификации. Проверьте свой API-ключ.

Учётная запись использует бесплатный тарифный план (для создания задач требуется платный план) или на ней недостаточно кредитов.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Уникальный идентификатор задачи. Хотя в качестве деталей реализации мы используем k-сортируемый UUID для идентификаторов задач, вам не следует делать никаких предположений о формате 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 запроса сборки. Не делайте никаких предположений о формате этих id.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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