lowpoly буде вимкнено 30 жовт. 2026 р.. Перейдіть на іншу модель до цих дат, щоб уникнути помилок у запитах. Усі застарілі функції

Creative Lab Fidget Pixel API

Перетворіть фотографію на багатоколірну пиксель-арт фіджет-дошку, придатну для 3D-друку, у два етапи. Задача прототипування перетворює фотографію на зображення у стилі піксель-арт. Задача побудови перетворює це зображення на деталі, що з'єднуються між собою, у єдиному файлі 3MF, і приймає ID задачі прототипування як input_task_id.

  • POST /openapi/creative-lab/fidget-pixel/v1/prototype
  • POST /openapi/creative-lab/fidget-pixel/v1/build

Обидва POST endpoint потребують платного тарифного плану. Запит з безкоштовного облікового запису повертає 402.

POST/openapi/creative-lab/fidget-pixel/v1/prototype

Create a Fidget Pixel prototype task

Генерує одне зображення у стилі піксель-арт із фотографії. Щоб створити деталі, передайте ID цього завдання до кінцевої точки побудови як input_task_id. Поля завдання описані в The Fidget Pixel prototype task object.

Якщо зображення вам не подобається, створіть ще одне завдання прототипу. Кожне завдання оплачується окремо.

Request

POST
/openapi/creative-lab/fidget-pixel/v1/prototype
# Stage 1: pixelize the source photo
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/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>",
    "type": "person"
  }'

Response

{
  "result": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7"
}

Параметри

  • Name
    image_url
    Type
    string
    Обов'язковий
    Description

    Фото, яке потрібно перетворити на піксель-арт, у вигляді публічної URL-адреси або Data URI (data:image/jpeg;base64,<your base64-encoded image data>).

    Зображення має бути файлом JPG, JPEG, PNG або WebP розміром не більше 20 МБ. Meshy визначає формат за даними зображення, а не за розширенням файлу в URL-адресі. URL без розширення теж працює, і Meshy переходить за перенаправленнями.

  • Name
    type
    Type
    string
    Обов'язковий
    Description

    Що зображено на фото — це визначає стиль піксель-арту. Два стилі помітно відрізняються. Будь-яке інше значення повертає 400.

    Доступні значення:

    • person: людина, на портреті або повнометражному фото. Meshy створює піксельний спрайт у стилі чиббі.
    • other: будь-який інший об'єкт, наприклад домашня тварина, предмет, маскот, логотип або пейзаж. Meshy створює піксельну іконку у стилі бісерного мистецтва.
  • Name
    name
    Type
    string
    Description

    Назва завдання, до 100 символів. Вона повертається в полі name завдання. Довша назва повертає 400.

Результат

Поле result містить ID нового завдання прототипу. Отримайте завдання або стримте його, поки status не стане SUCCEEDED. Потім передайте ID до кінцевої точки побудови як input_task_id.

Режими відмови

  • Name
    400 - Bad Request
    Description

    Запит не може бути виконаний. Наприклад:

    • Відсутній image_url або type.
    • type не дорівнює person або other.
    • Зображення не є файлом JPG, JPEG, PNG або WebP.
    • Зображення занадто мале, перевищує 20 МБ або перевищує максимальну кількість пікселів.
    • Meshy не може завантажити зображення, наприклад через те, що URL повертає 404 або час очікування вичерпано.
    • Data URI не є дійсним base64.
    • Зображення позначено як NSFW.

    Повідомлення про помилку вказує, яку проблему виявлено. Виправте запит і надішліть його знову.

  • Name
    401 - Unauthorized
    Description

    API-ключ відсутній або недійсний. Перевірте заголовок Authorization.

  • Name
    402 - Payment Required
    Description

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

    • На рахунку недостатньо кредитів.
    • API-ключ, робоча область або учасник досягли ліміту кредитів.
    • Обліковий запис перебуває на безкоштовному плані.

    Перевірте свої кредити та план, а потім повторіть спробу.

  • Name
    403 - Forbidden
    Description

    У вашій команді увімкнено IP Filtering, і Meshy позначив зображення як таке, що стосується інтелектуальної власності третьої сторони. Надішліть зображення, на використання якого у вас є права.

  • Name
    429 - Too Many Requests
    Description

    Досягнуто одного з таких обмежень:

    • Ви надіслали більше запитів, ніж дозволяє ваше обмеження частоти. Зачекайте кілька секунд, а потім повторіть спробу. Див. Rate limits.
    • Забагато ваших завдань перебувають у черзі або виконуються. Зачекайте, поки частина з них завершиться, а потім повторіть спробу.
    • На необмеженому плані без кредитів ви досягли кількості завдань, які можуть виконуватися без кредитів. Зачекайте завершення завдання або додайте кредити.
  • Name
    500 - Internal Server Error
    Description

    Meshy зіткнувся із серверною помилкою, наприклад через те, що не вдалося виконати перевірку зображення на інтелектуальну власність. Meshy не створює завдання та повертає будь-які стягнуті кредити. Повторіть запит.

POST/openapi/creative-lab/fidget-pixel/v1/build

Створення завдання на побудову Fidget Pixel

Генерує деталі, придатні для 3D-друку, на основі успішного завдання-прототипу. Meshy накладає зображення піксель-арту на сітку та зменшує його до щонайбільше color_count кольорів. Кожна клітинка об'єкта стає частиною, що з'єднується з іншими, а фон не друкується.

Результатом є один багатокольоровий файл 3MF, готовий до кольорового друку. Кожна деталь має сіре тіло та верхівку кольору свого пікселя. Опис полів див. у розділі Об'єкт завдання на побудову Fidget Pixel.

Request

POST
/openapi/creative-lab/fidget-pixel/v1/build
# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
    "options": {
      "shape": "square",
      "grid_size": 32,
      "piece_size_mm": 8,
      "color_count": 8,
      "piece_height_mm": 15
    },
    "output": {
      "format": "3mf"
    }
  }'

Response

{
  "result": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98"
}

Параметри

  • Name
    input_task_id
    Type
    string
    Обов'язковий
    Description

    ID завдання-прототипу для побудови. Це має бути завдання, створене вашим обліковим записом за допомогою POST /openapi/creative-lab/fidget-pixel/v1/prototype, зі статусом SUCCEEDED.

    ID, який не є одним із ваших завдань-прототипів Fidget Pixel, створених через API, повертає 404, включно з прототипом, створеним у веб-застосунку.

  • Name
    name
    Type
    string
    Description

    Назва завдання, до 100 символів. Вона повертається в полі name завдання. Довша назва повертає 400.

options

Налаштування форми та розміру деталей. Кожне поле має значення за замовчуванням, тож надсилайте лише ті поля, які хочете змінити. 0 використовує значення за замовчуванням для поля. Це ті самі налаштування, що й у веб-застосунку Creative Lab. Інші налаштування форми фіксовані, і Meshy встановлює їх на основі shape та piece_size_mm.

  • Name
    shape
    Type
    string
    за замовчуванням square
    Description

    Форма основи кожної деталі. Будь-яке інше значення повертає 400.

    Доступні значення:

    • square: квадратні деталі на квадратній сітці
    • hex: шестигранні деталі на шестигранній сітці, з piece_size_mm, встановленим на 6 або 8
  • Name
    grid_size
    Type
    integer
    за замовчуванням 32
    Description

    Кількість клітинок сітки вздовж кожної сторони плати, 16 або 32. Будь-яке інше значення повертає 400. Сітка 32 зберігає більше деталізації. Сітка 16 дає менше деталей того самого розміру, тому плата приблизно вдвічі вужча.

  • Name
    piece_size_mm
    Type
    integer
    за замовчуванням 8
    Description

    Довжина ребра кожної деталі в міліметрах, 6, 8 або 10. Будь-яке інше значення повертає 400. Разом із grid_size визначає розмір надрукованої плати. Наприклад, сітка 32 з деталями 8 мм становить близько 26,5 см на сторону.

    10 не працює з hex і повертає 400, оскільки похила грань шестигранника нависає на більшості споживчих FDM-принтерів.

  • Name
    color_count
    Type
    integer
    за замовчуванням 8
    Description

    Максимальна кількість кольорів у палітрі піксель-арту, від 1 до 8. Значення поза цим діапазоном повертає 400. Для друку вам потрібно до color_count плюс один філамент: один на колір і один для сірих тіл.

  • Name
    piece_height_mm
    Type
    integer
    за замовчуванням 15
    Description

    Висота кожної деталі в міліметрах, від 10 до 80. Значення поза цим діапазоном повертає 400.

output

Налаштування для результуючого файлу.

  • Name
    format
    Type
    string
    за замовчуванням 3mf
    Description

    Формат файлу результату. Будь-яке інше значення повертає 400.

    Доступні значення:

    • 3mf: один багатокольоровий файл model.3mf, що повертається в model_urls.3mf

Повернені значення

Поле result містить ID нового завдання на побудову. Отримайте завдання або транслюйте його, доки status не стане SUCCEEDED. Потім завантажте файл 3MF з model_urls.3mf.

Режими збою

  • Name
    400 - Bad Request
    Description

    Запит неможливо виконати. Наприклад:

    • input_task_id відсутній або не є дійсним ID завдання.
    • Статус завдання-прототипу не SUCCEEDED. Якщо воно ще виконується, зачекайте та повторіть спробу. Якщо воно завершилося невдало або було скасовано, створіть нове завдання-прототип.
    • Завдання-прототип завершилося успішно, але не має зображення. Створіть нове завдання-прототип.
    • Поле options виходить за межі дозволених значень, наприклад grid_size, відмінний від 16 або 32.
    • piece_size_mm дорівнює 10, а shape — hex. Шестигранні деталі доступні лише в 6 та 8 мм.
    • output.format не дорівнює 3mf.

    Повідомлення про помилку вказує, яку саме проблему знайдено.

  • Name
    401 - Unauthorized
    Description

    API-ключ відсутній або недійсний. Перевірте заголовок Authorization.

  • Name
    402 - Payment Required
    Description

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

    • На обліковому записі недостатньо кредитів.
    • API-ключ, робоча область або учасник досягли ліміту кредитів.
    • Обліковий запис перебуває на безкоштовному плані.

    Перевірте свої кредити та план, потім повторіть спробу.

  • Name
    403 - Forbidden
    Description

    У вашої команди увімкнено IP Filtering, і Meshy позначив зображення завдання-прототипу як таке, що порушує права інтелектуальної власності третіх осіб. Створіть завдання-прототип із зображення, на використання якого у вас є права.

  • Name
    404 - Not Found
    Description

    input_task_id не відповідає жодному завданню-прототипу Fidget Pixel, створеному вашим обліковим записом через API. Прототип, створений у веб-застосунку, також повертає 404. Надсилайте ID result із відповіді на створення прототипу.

  • Name
    429 - Too Many Requests
    Description

    Досягнуто одне з таких обмежень:

    • Ви надіслали більше запитів, ніж дозволяє ваше обмеження частоти. Зачекайте кілька секунд, потім повторіть спробу. Див. Обмеження частоти.
    • Забагато ваших завдань перебувають у черзі або виконуються. Зачекайте, доки деякі з них завершаться, потім повторіть спробу.
    • На необмеженому плані без залишку кредитів ви досягли кількості завдань, які можуть виконуватися без кредитів. Зачекайте завершення завдання або додайте кредити.
  • Name
    500 - Internal Server Error
    Description

    Meshy зіткнувся з серверною помилкою, наприклад через неможливість виконати перевірку на інтелектуальну власність щодо зображення завдання-прототипу. Meshy не створює завдання та повертає будь-які стягнуті кредити. Повторіть запит.

GET/openapi/creative-lab/fidget-pixel/v1/(prototype|build)/:id

Отримати завдання Fidget Pixel

Повертає завдання прототипу або збірки. Шлях має відповідати стадії завдання. Завдання збірки, запитане через /prototype/:id, повертає 404, те саме стосується завдання прототипу, запитаного через /build/:id.

Щодо полів дивіться Об'єкт завдання прототипу Fidget Pixel та Об'єкт завдання збірки Fidget Pixel.

Request

GET
/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7
# Prototype
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
  "type": "creative-lab-fidget-pixel-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001000000,
  "started_at": 1757001005000,
  "finished_at": 1757001178000,
  "expires_at": 1757260378000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
  ]
}

Build Response

{
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}

Параметри

  • Name
    id
    Type
    path
    Description

    ID завдання з відповіді на створення.

Повертає

Об'єкт завдання прототипу або об'єкт завдання збірки, відповідно до стадії, вказаної в шляху.

Режими відмови

  • Name
    400 - Bad Request
    Description

    id не є дійсним ID завдання. Надішліть ID result з відповіді на створення.

  • Name
    403 - Forbidden
    Description

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

  • Name
    404 - Not Found
    Description

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

  • Name
    500 - Internal Server Error
    Description

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

DELETE/openapi/creative-lab/fidget-pixel/v1/(prototype|build)/:id

Видалити завдання Fidget Pixel

Скасовує завдання Fidget Pixel. Скасування завдання зі статусом PENDING повертає витрачені кредити. Завдання зі статусом IN_PROGRESS скасовується без повернення коштів, оскільки воркер уже розпочав його виконання. Завдання з остаточним статусом (SUCCEEDED, FAILED або CANCELED) скасувати неможливо.

Шлях має відповідати етапу завдання. Наприклад, виклик DELETE для /prototype/:id з ID завдання build поверне 404.

Request

DELETE
/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7
curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 204 No Content on success (empty body).

Параметри шляху

  • Name
    id
    Type
    path
    Description

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

Повертає

204 No Content з порожнім тілом.

Випадки помилок

  • Name
    400 - Bad Request
    Description

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

    • id не є дійсним ID завдання. Надішліть ID result з відповіді на створення.
    • Завдання вже має остаточний статус (SUCCEEDED, FAILED або CANCELED), тому його неможливо скасувати.
  • Name
    404 - Not Found
    Description

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

GET/openapi/creative-lab/fidget-pixel/v1/(prototype|build)/:id/stream

Трансляція задачі Fidget Pixel

Транслює оновлення задачі Fidget Pixel у вигляді подій Server-Sent Events (SSE). Шлях має відповідати етапу задачі. Якщо ні, наприклад якщо ID задачі build передано за адресою /prototype/:id/stream, потік надішле одну подію error зі status_code: 404 і закриється. id, що не є дійсним ID задачі, призведе до того ж, але зі status_code: 400.

Request

GET
/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/stream
curl -N https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (wrong stage or task not found)
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// Every frame is the full task object for the stage; fields not yet populated are null / empty.
event: message
data: {
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "PENDING",
  "progress": 0,
  "created_at": 1757001300000,
  "started_at": null,
  "finished_at": null,
  "expires_at": 1757260500000,
  "preceding_tasks": 2,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {}
}

event: message
data: {
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}

Параметри

  • Name
    id
    Type
    path
    Description

    ID задачі з відповіді на створення.

Повертає

Потік об'єктів задачі prototype або build. Кожна подія містить повний об'єкт задачі, так само як його повертає Отримати задачу Fidget Pixel. Поки задача має статус PENDING або IN_PROGRESS, її вихідні поля все ще порожні (null, [] або {}), а finished_at дорівнює null.

Якщо IP Filtering блокує результат задачі, потік натомість надсилає одну подію error зі status_code, який повернув би звичайний get-запит.

GET/openapi/creative-lab/fidget-pixel/v1/(prototype|build)

Перелік завдань Fidget Pixel

Повертає ваші завдання Fidget Pixel одного етапу, по одній сторінці за раз. Шлях визначає етап. /prototype повертає лише завдання прототипу, а /build повертає лише завдання збірки.

Request

GET
/openapi/creative-lab/fidget-pixel/v1/prototype
# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response (List Prototype Tasks)

[
  {
    "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
    "type": "creative-lab-fidget-pixel-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1757001000000,
    "started_at": 1757001005000,
    "finished_at": 1757001178000,
    "expires_at": 1757260378000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
    ]
  }
]

Параметри шляху

  • Name
    stage
    Type
    path
    Обов'язковий
    Description

    Етап для перегляду, prototype або build.

Параметри запиту

  • Name
    page_num
    Type
    integer
    за замовчуванням 1
    Description

    Сторінка для повернення, від 1 до 255. 0 повертає першу сторінку. Значення поза межами 0–255 повертає 400.

  • Name
    page_size
    Type
    integer
    за замовчуванням 10
    Description

    Кількість завдань на сторінку, до 100. Значення від 101 до 255 повертає 100 завдань, а 0 використовує значення за замовчуванням. Значення поза межами 0–255 повертає 400.

  • Name
    sort_by
    Type
    string
    за замовчуванням -created_at
    Description

    Порядок сортування.

    Доступні значення:

    • -created_at: спочатку найновіші
    • +created_at: спочатку найстаріші

Повертає

Масив об'єктів завдань прототипу або об'єктів завдань збірки, що відповідають етапу, вказаному в шляху.

Об'єкт завдання прототипу Fidget Pixel

Завдання прототипу перетворює фотографію на зображення у стилі піксель-арт. Щоб перетворити зображення на деталі, придатні для 3D-друку, передайте ID завдання до кінцевої точки побудови як input_task_id.

Властивості

Example Fidget Pixel Prototype Task Object

{
  "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
  "type": "creative-lab-fidget-pixel-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001000000,
  "started_at": 1757001005000,
  "finished_at": 1757001178000,
  "expires_at": 1757260378000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
  ]
}
  • Name
    id
    Type
    string
    Description

    ID завдання. Не покладайтеся на його формат.

  • Name
    type
    Type
    string
    Description

    Тип завдання, завжди creative-lab-fidget-pixel-prototype.

  • Name
    name
    Type
    string
    Description

    name, яке ви надіслали під час створення завдання, або "", якщо ви його не надсилали.

  • Name
    status
    Type
    string
    Description

    Статус завдання.

    Доступні значення:

    • PENDING: очікує в черзі
    • IN_PROGRESS: генерується результат
    • SUCCEEDED: завершено, з результатом
    • FAILED: завершено, з причиною в task_error
    • CANCELED: завершено, без результату
  • Name
    progress
    Type
    integer
    Description

    Відсоток виконаної роботи, від 0 до 100. Дорівнює 0, доки завдання не почалося, і 100, коли воно успішно завершилося.

  • Name
    created_at
    Type
    timestamp
    Description

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

  • Name
    started_at
    Type
    timestamp
    Description

    Час, коли воркер почав виконувати завдання, у мілісекундах Unix. До цього — null.

  • Name
    finished_at
    Type
    timestamp
    Description

    Час, коли завдання досягло кінцевого статусу, у мілісекундах Unix. До цього — null.

  • Name
    expires_at
    Type
    timestamp
    Description

    Час, коли закінчується термін дії результату завдання, у мілісекундах Unix. Це 3 дні після finished_at, або 3 дні після created_at, доки завдання не завершиться. Для корпоративних (Enterprise) облікових записів, які зберігають результати API безстроково, це приблизно через 100 років. Див. Зберігання ресурсів.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Позиція завдання в черзі, поки воно має статус PENDING. 1 означає, що воно виконуватиметься наступним. 0 — після того, як завдання покинуло чергу, і завжди 0 у результатах списку.

  • Name
    task_error
    Type
    object
    Description

    Причина, через яку завдання завершилося невдало. null, якщо status не FAILED. Див. Помилки.

  • Name
    consumed_credits
    Type
    integer
    Description

    Кількість кредитів, списаних за завдання, після будь-якого повернення коштів. Запит, що повертає помилку, не оплачується. Невдале завдання має значення 0, оскільки Meshy повертає за нього кредити. Скасування повертає кредити за завдання лише доки воно має статус PENDING. Якщо Meshy не може визначити суму списання, відповідь на запит отримання або потокову передачу не міститиме цього поля, а запит списку поверне 500. У такому випадку повторіть запит.

  • Name
    image_urls
    Type
    array of strings
    Description

    URL-адреси для завантаження зображення у стилі піксель-арт. Масив містить одну URL-адресу після успішного завершення завдання, а до цього він порожній.

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

Об'єкт завдання збірки Fidget Pixel

Завдання збірки генерує деталі для 3D-друку з успішного завдання прототипування. Meshy накладає зображення пікс-арту на сітку та повертає деталі в одному багатокольоровому файлі 3MF.

Властивості

Example Fidget Pixel Build Task Object

{
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}
  • Name
    id
    Type
    string
    Description

    ID завдання. Не покладайтеся на його формат.

  • Name
    type
    Type
    string
    Description

    Тип завдання, завжди creative-lab-fidget-pixel-build.

  • Name
    name
    Type
    string
    Description

    Значення name, яке ви надіслали при створенні завдання, або "", якщо ви його не надсилали.

  • Name
    status
    Type
    string
    Description

    Статус завдання.

    Можливі значення:

    • PENDING: очікує в черзі
    • IN_PROGRESS: триває генерація результату
    • SUCCEEDED: завершено, з результатом
    • FAILED: завершено, з причиною в task_error
    • CANCELED: завершено, без результату
  • Name
    progress
    Type
    integer
    Description

    Відсоток виконаної роботи, від 0 до 100. Дорівнює 0, доки завдання не почалося, і 100, коли воно успішно завершене.

  • Name
    created_at
    Type
    timestamp
    Description

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

  • Name
    started_at
    Type
    timestamp
    Description

    Час, коли воркер почав виконувати завдання, у мілісекундах Unix. До цього моменту null.

  • Name
    finished_at
    Type
    timestamp
    Description

    Час, коли завдання досягло кінцевого статусу, у мілісекундах Unix. До цього моменту null.

  • Name
    expires_at
    Type
    timestamp
    Description

    Час, коли спливає термін дії результату завдання, у мілісекундах Unix. Це через 3 дні після finished_at, або через 3 дні після created_at, доки завдання не завершиться. Для облікових записів Enterprise, які зберігають результати API необмежено довго, це приблизно через 100 років. Див. Зберігання ресурсів.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Позиція завдання в черзі, поки воно має статус PENDING. 1 означає, що воно виконається наступним. 0 після того, як завдання залишає чергу, і завжди 0 у результатах списку.

  • Name
    task_error
    Type
    object
    Description

    Причина, через яку завдання завершилося невдало. null, якщо status не дорівнює FAILED. Див. Помилки.

  • Name
    consumed_credits
    Type
    integer
    Description

    Кількість кредитів, списаних за завдання, після будь-якого повернення коштів. Запит, що повертає помилку, не оплачується. Для невдалого завдання це 0, оскільки Meshy повертає кошти. Скасування повертає кошти за завдання, лише доки воно має статус PENDING. Якщо Meshy не може прочитати суму списання, у відповіді на get-запит або потік це поле відсутнє, а запит списку повертає 500. У такому разі повторіть запит.

  • Name
    model_urls
    Type
    object
    Description

    URL-адреси для завантаження результату, за ключами форматів файлів. Об'єкт містить один запис — для output.format, який ви надіслали, — і залишається порожнім, доки завдання не завершиться успішно.

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

    • Name
      3mf
      Type
      string
      Description

      URL-адреса для завантаження багатокольорового файлу 3MF. Кожна деталь має сіре тіло та верхівку кольору свого пікселя. Присутня, коли output.format дорівнює 3mf, що є значенням за замовчуванням.

Наскрізний приклад

Наступні скрипти cURL та Python виконують весь процес. Кожен скрипт створює завдання прототипу з фотографії та очікує на його успішне завершення. Потім він створює завдання побудови, очікує на його завершення та завантажує файл 3MF з model_urls.3mf.

Для скрипту cURL потрібні curl та jq, а для скрипту Python потрібен пакет requests. Щоб запустити скрипт, виконайте такі кроки:

  1. Встановіть MESHY_API_KEY на ваш API-ключ.
  2. Встановіть IMAGE_PATH на шлях до локальної фотографії, або IMAGE_URL на публічну URL-адресу зображення.
  3. Необов'язково: щоб піксельувати не людину, а інший об'єкт, встановіть PIXEL_TYPE на other.
  4. Запустіть скрипт.

Завдання прототипу зазвичай завершується протягом кількох хвилин. Завдання побудови зазвичай завершується менш ніж за хвилину.

У вашому застосунку показуйте зображення з image_urls користувачу перед створенням завдання побудови. Якщо воно йому не сподобається, створіть ще одне завдання прототипу замість цього. Таким чином ви витрачаєте кредити на побудову лише для зображення, яке він схвалив.

Complete flow

POST
/openapi/creative-lab/fidget-pixel/v1
#!/usr/bin/env bash
set -euo pipefail

# Requires curl and jq. Point IMAGE_PATH at a local photo, or IMAGE_URL at a public one:
#   export MESHY_API_KEY=msy_...
#   export IMAGE_PATH=./portrait.jpg          # or: export IMAGE_URL=https://...
#   export PIXEL_TYPE=person                  # or: other
: "${MESHY_API_KEY:?export MESHY_API_KEY first}"
if [[ -z "${IMAGE_PATH:-}" && -z "${IMAGE_URL:-}" ]]; then
  echo "export IMAGE_PATH (local file) or IMAGE_URL (public url) first" >&2
  exit 1
fi
PIXEL_TYPE=${PIXEL_TYPE:-person}

BASE="https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1"
AUTH="Authorization: Bearer $MESHY_API_KEY"

# api METHOD URL [curl args...] -> prints the response body, non-zero on failure.
# Note we do not use -f/--fail: it discards the body, and the body is the only
# place the reason appears.
api() {
  local method=$1 url=$2 out http_code body
  shift 2
  out=$(curl --silent --show-error --max-time 60 --write-out $'\n%{http_code}' \
    -X "$method" "$url" -H "$AUTH" "$@") || return 1
  http_code=${out##*$'\n'}
  body=${out%$'\n'*}
  if ((http_code >= 400)); then
    echo "HTTP $http_code for $url: $body" >&2
    return 1
  fi
  printf '%s' "$body"
}

# Each task gets its own 40-minute budget.
poll() {
  local kind=$1 id=$2 delay=5 task_status deadline
  deadline=$(($(date +%s) + 2400))
  while :; do
    if (($(date +%s) >= deadline)); then
      echo "gave up waiting for $kind $id" >&2
      return 1
    fi
    task_status=$(api GET "$BASE/$kind/$id" | jq -r '.status')
    echo "$kind: $task_status"
    case "$task_status" in
    SUCCEEDED) return 0 ;;
    FAILED | CANCELED) return 1 ;;
    esac
    sleep "$delay"
    delay=$((delay * 2 > 30 ? 30 : delay * 2))
  done
}

# Build the request body in a file. A base64 data URI must never go on the
# command line or into an exported variable - a photo of any real size will
# exceed the OS argument limit.
BODY=$(mktemp)
trap 'rm -f "$BODY"' EXIT
if [[ -n "${IMAGE_PATH:-}" ]]; then
  # Declare the real type: the API accepts JPEG, PNG and WebP.
  case "$(printf '%s' "${IMAGE_PATH##*.}" | tr 'A-Z' 'a-z')" in
    png) MIME=image/png ;;
    webp) MIME=image/webp ;;
    *) MIME=image/jpeg ;;
  esac
  {
    printf '{"type":"%s","image_url":"data:%s;base64,' "$PIXEL_TYPE" "$MIME"
    base64 <"$IMAGE_PATH" | tr -d '\n'
    printf '"}'
  } >"$BODY"
else
  jq -n --arg t "$PIXEL_TYPE" --arg u "$IMAGE_URL" \
    '{type: $t, image_url: $u}' >"$BODY"
fi

# 1. Create the prototype task
PROTO_ID=$(api POST "$BASE/prototype" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 2. Wait for the pixel-art image (show image_urls[0] to a user in production)
poll prototype "$PROTO_ID"

# 3. Create the build task (defaults: square pieces, 32x32 grid, 8 mm, 8 colors, 15 mm tall)
jq -n --arg p "$PROTO_ID" \
  '{input_task_id: $p, options: {shape: "square", grid_size: 32, piece_size_mm: 8, color_count: 8, piece_height_mm: 15}, output: {format: "3mf"}}' >"$BODY"
BUILD_ID=$(api POST "$BASE/build" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 4. Wait for the pieces
poll build "$BUILD_ID"

# 5. Download the 3MF. This is a signed URL: no Authorization header,
#    and it stays valid for 3 days after the task finishes.
TASK=$(api GET "$BASE/build/$BUILD_ID")
curl --silent --show-error --fail --max-time 900 \
  -o fidget-pixel.3mf "$(jq -r '.model_urls["3mf"]' <<<"$TASK")"
echo "Done: fidget-pixel.3mf"