Перетворіть вихідну фотографію на придатний для 3D-друку медальйон-брелок — рельєф глибини
у формі значка з кольорами — у два етапи: prototype генерує кольорове
концептуальне зображення з вашої вхідної фотографії, а потім build перетворює це концептуальне зображення
на рельєфну 3D-модель. Два етапи пов’язані через input_task_id.
Згенеруйте одне колоризоване концептуальне зображення з вихідної фотографії. Повернений ID завдання — це те, що ви передаєте як input_task_id до кінцевої точки build. Див.
Об’єкт завдання прототипу брелока
щодо структури відповіді.
Параметри
Name
image_url
Type
string
Обов'язковий
Description
Вихідна фотографія, яку Meshy має колоризувати в концептуальне зображення, готове для брелока. Наразі ми підтримуємо формати .jpg, .jpeg, .png і .webp.
Є два способи надати зображення:
Публічно доступна URL-адреса: URL-адреса, доступна з публічного інтернету.
Data URI: Data URI зображення, закодований у base64. Приклад Data URI: data:image/jpeg;base64,<your base64-encoded image data>.
Name
name
Type
string
Description
Необов’язкова назва завдання для відображення. Максимум 100 символів.
Повертає
Властивість result відповіді містить id завдання новоствореного завдання прототипу брелока. Опитуйте кінцеву точку Отримати завдання або підпишіться на потік, доки завдання не досягне SUCCEEDED, а потім передайте цей ID до кінцевої точки build як input_task_id.
Випадки помилок
Name
400 - Bad Request
Description
Запит був неприйнятним. Поширені причини:
Відсутній параметр: image_url є обов’язковим.
Недійсний формат зображення: Наданий image_url не є підтримуваним форматом (.jpg, .jpeg, .png, .webp).
Розміри зображення поза діапазоном: Зображення замале, перевищує максимальний розмір файлу або перевищує максимальну кількість пікселів.
Недосяжна URL-адреса: image_url не вдалося завантажити (404 або timeout).
Недійсний Data URI: Рядок base64 має неправильний формат.
Вміст позначено: Вхідне зображення було позначене moderation щодо NSFW або інтелектуальної власності.
Name
401 - Unauthorized
Description
Автентифікація не вдалася. Перевірте свій API-ключ.
Name
402 - Payment Required
Description
Недостатньо кредитів для виконання цього завдання.
Name
429 - Too Many Requests
Description
Ви перевищили своє обмеження частоти.
Request
POST
/openapi/creative-lab/keychain/v1/prototype
# Stage 1: generate a colorized keychain concept imagecurl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype \ -X POST \ -H "Authorization: Bearer ${YOUR_API_KEY}" \ -H 'Content-Type: application/json' \ -d '{ "image_url": "<your publicly accessible image url or base64-encoded data URI>" }'
Response
{"result":"018a210d-8ba4-705c-b111-1f1776f7f578"}
Prototype example
Start with a source photo, then generate the prototype image used by the keychain build stage.
Згенеруйте фінальний медальйон-брелок для 3D-друку із завдання
прототипу, що завершилося успішно. Збірка запускає конвеєр рельєфу на
основі карти глибини для колоризованого концепт-зображення прототипу та
постачає один артефакт сітки у запитаному вами форматі. Див.
Об’єкт завдання збірки брелока щодо
форми відповіді.
Параметри
Name
input_task_id
Type
string
Обов'язковий
Description
ID завдання прототипу, створеного через цю саму кінцеву точку OpenAPI. Прототип має бути створений із тим самим API-ключем, має досягти SUCCEEDED і має створити рівно одне зображення-кандидат.
Завдання прототипів, створені через вебзастосунок, не приймаються — кінцева точка збірки приймає лише завдання прототипів, створені через POST /openapi/creative-lab/keychain/v1/prototype, і відхиляє будь-яке інше джерело з 404.
Name
name
Type
string
Description
Необов’язкова назва завдання для відображення. Максимум 100 символів.
options
Необов’язкові параметри налаштування для геометрії рельєфу. Кожне поле має розумне значення за замовчуванням — надсилайте лише ті, які хочете перевизначити.
glb (за замовчуванням) — повертає один model.glb у model_urls.glb.
obj — стискає model.obj + model.mtl + texture.png у zip і повертає пакет у model_urls.obj.
zip — стискає в zip кожен артефакт, який видає генератор, і повертає пакет у model_urls.bundle_zip.
Повертає
Властивість result відповіді містить id завдання щойно створеного завдання збірки брелока. Опитуйте кінцеву точку Отримати завдання або підпишіться на потік, доки завдання не досягне SUCCEEDED, а потім завантажте артефакт з єдиного запису в model_urls.
Режими відмови
Name
400 - Bad Request
Description
Запит був неприйнятним. Поширені причини:
Відсутній параметр: input_task_id є обов’язковим.
Недійсний UUID: input_task_id не є дійсним UUID.
Батьківське завдання не завершилося успішно: завдання прототипу, на яке є посилання, ще не досягло SUCCEEDED.
Немає кандидата: завдання прототипу завершилося успішно, але не створило зображення-кандидат.
Параметри поза діапазоном: одне з полів options опинилося поза дозволеним діапазоном або набором enum.
Name
401 - Unauthorized
Description
Автентифікація не вдалася. Перевірте свій API-ключ.
Name
402 - Payment Required
Description
Недостатньо кредитів для виконання цього завдання.
Name
404 - Not Found
Description
Завдання прототипу, на яке є посилання, не існує, належить іншому користувачу або було створене через вебзастосунок (лише завдання прототипів у API-mode можна послідовно передавати в збірку).
Отримайте завдання прототипу або збірки за дійсним id завдання. Шлях URL
має відповідати етапу завдання — завдання збірки, отримане через
/prototype/:id, повертає 404, і навпаки.
Скасувати завдання брелока. Якщо завдання все ще має стан PENDING, кредити,
спожиті під час створення, повертаються. Завдання, які вже перебувають у стані
IN_PROGRESS, скасовуються без повернення (обробник, можливо, вже
витрачає ресурси). Завдання, які вже досягли кінцевого стану
(SUCCEEDED, FAILED, CANCELED), не можна скасувати.
Шлях URL має відповідати етапу завдання — DELETE для
/prototype/:buildId повертає 404.
Параметри шляху
Name
id
Type
path
Description
Унікальний ідентифікатор завдання брелока, яке потрібно скасувати.
Повертає
Повертає 204 No Content у разі успіху з порожнім тілом.
Режими помилок
Name
400 - Bad Request
Description
Завдання вже перебуває в кінцевому стані й не може бути скасоване.
Name
404 - Not Found
Description
Завдання не існує, належить іншому користувачу або його етап не відповідає шляху URL.
Отримуйте в реальному часі оновлення для завдання брелока через SSE.
Шлях URL має відповідати етапу завдання — відкриття потоку за
/prototype/:buildId/stream надсилає одне корисне навантаження event: error із
status_code: 404 і закриває потік.
Параметри
Name
id
Type
path
Description
Унікальний ідентифікатор завдання брелока для потокового передавання.
Повертає
Повертає потік об’єктів завдань прототипу брелока
або збірки брелока як
SSE. Для завдань PENDING або IN_PROGRESS потік відповіді
міститиме лише необхідні поля progress і status.
// Error event example (wrong stage or task not found)event: errordata: {"status_code": 404,"message": "Task not found"}// Message event examples illustrate task progress.// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.event: messagedata: {"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb","progress": 0,"status": "PENDING"}event: messagedata: {"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb","type": "creative-lab-keychain-build","status": "SUCCEEDED","progress": 100,"created_at": 1729123500000,"started_at": 1729123510000,"finished_at": 1729123535000,"expires_at": 1729382735000,"task_error": null,"consumed_credits": 20,"model_urls": {"glb":"https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***" }}
Отримайте пагінований список ваших завдань брелока для одного етапу. Шлях
URL вибирає етап — /prototype повертає завдання прототипу; /build
повертає завдання збірки. Завдання з іншого етапу не включаються в жодну
відповідь.
Параметри шляху
Name
stage
Type
path
Обов'язковий
Description
Або prototype, або build. Колекція повертає лише завдання,
етап яких відповідає URL — отримання /prototype ніколи не повертає
завдання збірки, і навпаки.
Параметри запиту
Name
page_num
Type
integer
за замовчуванням 1
Description
Номер сторінки для пагінації.
Name
page_size
Type
integer
за замовчуванням 10
Description
Обмеження розміру сторінки. Максимально дозволено 50 елементів.
Name
sort_by
Type
string
за замовчуванням -created_at
Description
Поле для сортування. Доступні значення:
+created_at: Сортувати за часом створення в порядку зростання.
-created_at: Сортувати за часом створення в порядку спадання.
Об’єкт завдання прототипу брелока — це робоча одиниця, яку Meshy відстежує для
створення кольоризованого концептуального зображення з вихідної фотографії. Вихідні дані
цього етапу передаються в етап побудови
через input_task_id.
Властивості
Name
id
Type
string
Description
Унікальний ідентифікатор завдання. Хоча як деталь реалізації для ідентифікаторів завдань ми використовуємо k-сортований UUID, вам не слід робити жодних припущень щодо формату id.
Name
type
Type
string
Description
Тип завдання. Значення — creative-lab-keychain-prototype.
Name
name
Type
string
Description
Назва завдання, надана під час створення завдання. Порожній рядок, якщо назву не було надано.
Name
status
Type
string
Description
Статус завдання. Можливі значення: одне з PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
progress завдання. Якщо завдання ще не запущено, ця властивість буде 0. Щойно завдання успішно завершиться, вона стане 100.
Name
created_at
Type
timestamp
Description
Мітка часу, коли завдання було створено, у мілісекундах.
Мітка часу представляє кількість мілісекунд, що минули з 1 січня 1970 року UTC, відповідно до
стандарту RFC 3339.
Наприклад, п’ятниця, 1 вересня 2023 року, 12:00:00 PM GMT представлена як 1693569600000. Це застосовується
до всіх міток часу в Meshy API.
Name
started_at
Type
timestamp
Description
Мітка часу, коли завдання було запущено, у мілісекундах. Якщо завдання ще не запущено, ця властивість буде 0.
Name
finished_at
Type
timestamp
Description
Мітка часу, коли завдання було завершено, у мілісекундах. Якщо завдання ще не завершено, ця властивість буде 0.
Name
expires_at
Type
timestamp
Description
Мітка часу, коли результат завдання закінчує термін дії, у мілісекундах.
Name
preceding_tasks
Type
integer
Description
Кількість попередніх завдань.
Значення цього поля має сенс лише якщо статус завдання — PENDING.
Name
task_error
Type
object
Description
Відомості про помилку для невдалих завдань. Див. Помилки для повної довідки щодо об’єкта task_error.
Name
consumed_credits
Type
integer
Description
Кількість кредитів, спожитих цим завданням. Наявна, коли статус завдання — PENDING, IN_PROGRESS або SUCCEEDED. Повертає 0 для завдань FAILED (кредити повертаються в разі невдачі).
Name
image_urls
Type
array of strings
Description
URL-адреси для завантаження кандидатів концептуальних зображень, згенерованих цим прототипним завданням. Наразі API завжди повертає рівно одного кандидата; поле є масивом, щоб майбутні версії могли відображати кількох кандидатів без критичної зміни.
Об’єкт завдання збірки брелока — це робоча одиниця, яку Meshy відстежує, щоб
згенерувати фінальну 3D-сітку брелока з успішно виконаного завдання прототипу.
Збірка запускає конвеєр рельєфу на основі карти глибини для концепт-зображення прототипу та
публікує єдиний артефакт сітки у форматі, який запитав викликач.
Властивості
Name
id
Type
string
Description
Унікальний ідентифікатор завдання.
Name
type
Type
string
Description
Тип завдання. Значення — creative-lab-keychain-build.
Name
name
Type
string
Description
Назва завдання, надана під час створення завдання. Порожній рядок, якщо назву не було надано.
Name
status
Type
string
Description
Статус завдання. Можливі значення: одне з PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
progress завдання. Якщо завдання ще не розпочато, ця властивість буде 0. Щойно завдання буде успішно виконано, вона стане 100.
Name
created_at
Type
timestamp
Description
Мітка часу створення завдання, у мілісекундах.
Name
started_at
Type
timestamp
Description
Мітка часу початку завдання, у мілісекундах.
Name
finished_at
Type
timestamp
Description
Мітка часу завершення завдання, у мілісекундах.
Name
expires_at
Type
timestamp
Description
Мітка часу завершення терміну дії результату завдання, у мілісекундах.
Name
preceding_tasks
Type
integer
Description
Кількість попередніх завдань. Має значення лише тоді, коли статус — PENDING.
Name
task_error
Type
object
Description
Відомості про помилку для невдалих завдань. Див. Помилки для повної довідки щодо об’єкта task_error.
Name
consumed_credits
Type
integer
Description
Кількість кредитів, спожитих цим завданням. Повертає 0 для завдань FAILED (кредити повертаються в разі невдачі).
Name
model_urls
Type
object
Description
Завантажувані URL-адреси для згенерованого артефакту, згруповані за назвою артефакту. Завжди містить рівно один запис — формат, запитаний через output.format запиту на побудову. Ключ відповідає запитаному формату:
Name
glb
Type
string
Description
Завантажувана URL-адреса до файлу GLB. Присутня, коли output.format був glb (за замовчуванням).
Name
obj
Type
string
Description
Завантажувана URL-адреса до zip-пакета, що містить model.obj, model.mtl і texture.png. Присутня, коли output.format був obj.
Name
bundle_zip
Type
string
Description
Завантажувана URL-адреса до zip-пакета кожного артефакту, який видає генератор. Присутня, коли output.format був zip.