Creative Lab Keycap API

Фотографія, яку потрібно перетворити на дизайн ковпачка клавіші, у вигляді публічного 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, щоб ви могли розмістити ковпачок клавіші на будь-якому фоні. Якщо Meshy не може видалити фон, повертається зображення з фоном, і завдання все одно завершується успішно.

Дизайн верхньої частини, який при побудові перетворюється на 3D, зберігає свій фон у будь-якому випадку. Побудова малює основу ковпачка клавіші із зображення в 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 зіткнувся з помилкою сервера, наприклад через те, що не вдалося виконати модерацію контенту (moderation) або перевірку інтелектуальної власності, або 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, і Meshy позначив зображення завдання прототипу через права інтелектуальної власності третіх сторін. Завдання збірки та команди на плані Enterprise не отримують цю помилку. Створіть завдання прототипу із зображення, на використання якого ви маєте права.

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

Meshy не зміг виконати перевірку інтелектуальної власності. Повторіть запит.

Ідентифікатор задачі, яку потрібно скасувати.

Застосовується одне з наведеного:

• id не є дійсним ідентифікатором задачі. Надішліть ідентифікатор result з відповіді на створення.
• Задача вже має фінальний статус (SUCCEEDED, FAILED або CANCELED), тому її не можна скасувати.

Задача Keycap з таким ідентифікатором не належить вашому акаунту, або етап задачі не відповідає шляху. Перевірте ідентифікатор і використовуйте /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 не може зчитати стягнення, у відповіді на get-запит або потоковій відповіді це поле відсутнє, а запит списку повертає 500. У такому разі повторіть запит.

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

Ці URL-адреси призначені для відображення. Кінцева точка build приймає запис із candidate_ids, а не URL-адресу. Це підписані URL-адреси, тож отримуйте їх без заголовка Authorization. Вони залишаються дійсними до expires_at, і повторне отримання завдання повертає ті самі URL-адреси.

ID кандидатів, у тому ж порядку, що й image_urls. Щоб побудувати кандидата, надішліть його ID як candidate_id у запиті build. Не покладайтеся на формат цих 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 вгору, передньою стороною keycap, спрямованою до +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: зображення готового keycap для обраного кандидата, з якого збірка зафарбувала основу. Може бути відсутнім.
• base_canvas: зафарбована основа keycap. Може бути відсутньою.

Meshy може додавати ключі, тому ігноруйте ключ, який ви не розпізнаєте.