Creative Lab — Keycap API

Вихідне фото, яке Meshy перетворить на зображення дизайну кейкапа. Наразі підтримуються формати .jpg, .jpeg, .png та .webp.

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

Це стосується лише відображуваного рендера. Кандидат, який використовує endpoint для build, залишається незмінним, тому 3D-результат буде однаковим в обох випадках.

Запит неприпустимий. Поширені причини:

• Відсутній параметр: image_url є обов'язковим.
• Недійсний формат зображення: наданий image_url має непідтримуваний формат (.jpg, .jpeg, .png, .webp).
• Розміри зображення поза межами діапазону: зображення занадто мале, перевищує максимальний розмір файлу або максимальну кількість пікселів.
• Недоступний URL: не вдалося завантажити image_url (404 або timeout).
• Недійсний Data URI: рядок base64 некоректний.
• Контент позначено: вхідне зображення було позначено системою moderation NSFW-контенту.

Помилка автентифікації. Перевірте свій API-ключ.

Обліковий запис перебуває на безкоштовному тарифі (для створення завдань потрібен платний тариф) або має недостатньо кредитів.

Вхідне зображення було позначено системою moderation інтелектуальної власності.

Ви перевищили своє обмеження частоти.

Сталася неочікувана помилка на стороні сервера — наприклад, сервіс модерації контенту був недоступний, не вдалося виконати проміжне збереження вхідного зображення, або не вдалося створити завдання. У цьому випадку завдання не створюється, тому повторити спробу безпечно.

Ідентифікатор завдання-прототипу, створеного через цю саму кінцеву точку OpenAPI. Прототип має бути створений тим самим обліковим записом Meshy, повинен досягти статусу SUCCEEDED і має мати щонайменше одного кандидата.

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

Кандидат, який потрібно побудувати, взятий з масиву candidate_ids успішного завдання-прототипу. Має належати цьому завданню; будь-яке інше значення відхиляється з кодом 400.

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

Основа ковпачка клавіші, на якій виконується побудова. Наразі єдине доступне значення — cherry-mx-1x1-r1 — стандартний ковпачок клавіші Cherry MX profile 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.

Progress завдання. Якщо завдання ще не почалося, ця властивість матиме значення 0. Коли завдання успішно завершиться, воно стане 100.

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

Мітка часу початку виконання завдання, у мілісекундах. Якщо завдання ще не почалося, ця властивість матиме значення 0.

Мітка часу завершення завдання, у мілісекундах. Якщо завдання ще не завершено, ця властивість матиме значення 0.

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

Кількість завдань, що передують цьому.

Деталі помилки для завдань, що завершилися невдало. Див. Помилки для повного опису об'єкта task_error.

Кількість кредитів, витрачених на це завдання. Завдання, що досягає статусу SUCCEEDED, оплачується повністю за свій етап. Завдання, яке ніколи не було створене (помилка 4xx під час запиту, включно з відхиленням через moderation), не оплачується взагалі. Завдання, що досягає статусу FAILED, повертає 0 — оплата повертається, включно з випадком асинхронного блокування через moderation. Скасування через 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-up, при цьому передня частина клавіші звернена до +Z. Сітки (meshes) названі keycap-head та keycap-base; коли основа переходить до заповнення за шаблоном (pattern fill), також присутня третя сітка keycap-base-interior для порожнини під стрижень. Не припускайте, що завжди буде рівно дві сітки.

Це підписані URL-адреси: отримуйте їх без заголовка Authorization. Вони залишаються дійсними до expires_at, що становить 3 дні після finished_at, і повторне читання задачі протягом цього періоду повертає ідентичний URL, а не заново підписаний. Завантажте та збережіть файли самостійно до цього моменту — способу оновити застарілу URL-адресу не існує.

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

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

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