Creative Lab — API Fidget Pixel

Превратите исходное фото в многоцветную пиксель-арт фиджет-панель, готовую к 3D-печати, в два этапа: prototype превращает ваше фото в пиксель-арт изображение, затем build накладывает это изображение на сетку 16×16 или 32×32 и превращает каждый пиксель в скрепляющуюся квадратную или шестиугольную деталь, результат выдаётся в виде единого файла 3MF, объекты которого несут информацию о своём цвете, так что многофиламентный слайсер печатает каждую деталь нужным цветом. Оба этапа связаны через input_task_id.

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

Оба POST endpoint требуют платной подписки. Запросы от аккаунтов с бесплатным тарифным планом отклоняются с ошибкой 402 Payment Required.

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

Create a Fidget Pixel Prototype Task

Сгенерируйте единственное изображение в стиле пиксель-арт из исходной фотографии. Возвращаемый ID задачи — это то, что вы передаёте как input_task_id в эндпоинт сборки. Вызовите этот эндпоинт снова для другой попытки, если результат вас не устраивает — каждый вызов оплачивается отдельно. Обратитесь к разделу Объект Fidget Pixel Prototype Task для описания формата ответа.

Параметры

  • Name
    image_url
    Type
    string
    Обязательный
    Description

    Исходная фотография, которую Meshy пикселизирует. В настоящее время поддерживаются форматы .jpg, .jpeg, .png и .webp.

    Формат определяется путём декодирования данных изображения, а не по расширению файла в URL — URL без расширения или с редиректом сработает, если байты декодируются в поддерживаемый формат. HTTP-редиректы обрабатываются.

    Есть два способа предоставить изображение:

    • Публично доступный URL: URL, доступный из публичного интернета.
    • Data URI: изображение, закодированное в base64 в виде data URI. Пример data URI: data:image/jpeg;base64,<ваши закодированные в base64 данные изображения>.
  • Name
    type
    Type
    string
    Обязательный
    Description

    Что изображено на фотографии. Определяет стиль пикселизации, поэтому выбирайте осознанно — эти два варианта дают заметно разные результаты. Доступные значения:

    • person — на фото человек (портрет или в полный рост). Создаёт пиксельный спрайт субъекта в стиле чиби.
    • other — что-либо ещё: питомцы, объекты, талисманы, логотипы, пейзажи. Создаёт пиксельную иконку субъекта в стиле бисерного искусства.
  • Name
    name
    Type
    string
    Description

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

Возвращаемые значения

Свойство result ответа содержит id только что созданной задачи прототипа fidget pixel. Опрашивайте эндпоинт Get a Task или подпишитесь на поток, пока задача не достигнет статуса SUCCEEDED, затем передайте этот ID в эндпоинт сборки как input_task_id.

Режимы отказа

  • Name
    400 - Bad Request
    Description

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

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

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

  • Name
    402 - Payment Required
    Description

    Недостаточно кредитов для выполнения этой задачи, либо API-ключ принадлежит аккаунту с бесплатным тарифом.

  • Name
    403 - Forbidden
    Description

    Входное изображение было отмечено модерацией интеллектуальной собственности (Content flagged for intellectual property violation). Блокируются только Enterprise-аккаунты с включённой фильтрацией интеллектуальной собственности; списание средств не производится.

  • Name
    429 - Too Many Requests
    Description

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

  • Name
    500 - Internal Server Error
    Description

    Не удалось выполнить саму проверку на интеллектуальную собственность (Unable to perform intellectual property check, please try again). Enterprise-аккаунты с включённой фильтрацией интеллектуальной собственности в этом случае блокируют запрос по умолчанию (fail closed); списание средств не производится — повторите запрос.

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"
}
POST/openapi/creative-lab/fidget-pixel/v1/build

Создание задачи сборки Fidget Pixel

Генерирует части для 3D-печати на основе успешно завершённой задачи прототипа. Сборка сэмплирует пиксель-арт изображение прототипа на запрошенную сетку, квантует его до не более чем color_count цветов и генерирует одну соединяемую деталь на каждую ячейку сетки. Результатом является единый файл 3MF, в котором каждая деталь представляет собой отдельный объект с прикреплённым к нему цветом, готовый для многофиламентного слайсера. Форму ответа см. в разделе Объект задачи сборки Fidget Pixel.

Параметры

  • Name
    input_task_id
    Type
    string
    Обязательный
    Description

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

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

  • Name
    name
    Type
    string
    Description

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

options

Необязательная геометрия детали. У каждого поля есть значение по умолчанию — отправляйте только те, которые вы хотите переопределить. Это те же элементы управления, которые доступны в веб-приложении Creative Lab; высота штифта, масштаб колпачка и другие производственные предустановки выводятся из shape и piece_size_mm и не выставляются напрямую.

  • Name
    shape
    Type
    string
    по умолчанию square
    Description

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

    • square (по умолчанию) — квадратные детали на квадратной сетке.
    • hex — шестиугольные детали на шестиугольной сетке. Шестиугольные детали доступны только в размерах 6 и 8 мм.
  • Name
    grid_size
    Type
    integer
    по умолчанию 32
    Description

    Количество деталей вдоль каждой стороны платы. Доступные значения: 16 или 32. Сетка 32 сохраняет больше деталей; сетка 16 означает меньшее количество более крупных деталей для того же сюжета.

  • Name
    piece_size_mm
    Type
    integer
    по умолчанию 8
    Description

    Длина стороны каждой детали, в миллиметрах. Доступные значения: 6, 8 или 10. В сочетании с grid_size это задаёт печатаемый размер платы — например, 32 × 8 мм ≈ 26 см на сторону. 10 недоступно для shape: "hex" (наклонная грань шестиугольника создаёт свес на большинстве потребительских принтеров FDM).

  • Name
    color_count
    Type
    integer
    по умолчанию 8
    Description

    Максимальное количество цветов в палитре, до которой квантуется изображение. Диапазон: [1, 8]. Каждый цвет становится одним филаментом в вашем слайсере.

  • Name
    piece_height_mm
    Type
    integer
    по умолчанию 15
    Description

    Высота каждой детали, в миллиметрах. Диапазон: [10, 80].

output

Необязательный селектор формата данных. По умолчанию 3mf, что на данный момент является единственным поддерживаемым значением.

  • Name
    format
    Type
    string
    по умолчанию 3mf
    Description

    Артефакт, возвращаемый сборкой. Доступные значения:

    • 3mf (по умолчанию) — возвращает единый файл model.3mf в model_urls.3mf, с одним объектом на деталь и цветом детали, прикреплённым к каждому объекту.

Возвращаемое значение

Свойство result ответа содержит id задачи только что созданной задачи сборки Fidget Pixel. Опрашивайте эндпоинт Получение задачи или подпишитесь на поток, пока задача не достигнет статуса SUCCEEDED, затем скачайте артефакт из model_urls.3mf.

Режимы отказа

  • Name
    400 - Bad Request
    Description

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

    • Отсутствует параметр: input_task_id обязателен.
    • Недействительный UUID: input_task_id не является допустимым UUID.
    • Родительская задача не завершена успешно: указанная задача прототипа ещё не достигла статуса SUCCEEDED.
    • Нет кандидата: задача прототипа завершилась успешно, но не создала пиксель-арт изображение; создайте новый прототип.
    • Параметры вне диапазона: одно из полей options выходит за пределы допустимого набора или диапазона — например, options.grid_size must be 16 or 32, или options.piece_size_mm=10 is not supported for shape=hex; hex pieces are available in 6 and 8 mm.
    • Неподдерживаемый формат: output.format должен быть 3mf.
  • Name
    401 - Unauthorized
    Description

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

  • Name
    402 - Payment Required
    Description

    Недостаточно кредитов для выполнения этой задачи, либо API-ключ принадлежит учётной записи бесплатного тарифа.

  • Name
    403 - Forbidden
    Description

    Изображение указанного прототипа было помечено модерацией интеллектуальной собственности. Блокируются только учётные записи Enterprise с включённой фильтрацией интеллектуальной собственности; списание средств не производится.

  • Name
    404 - Not Found
    Description

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

  • Name
    429 - Too Many Requests
    Description

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

  • Name
    500 - Internal Server Error
    Description

    Не удалось установить вердикт по интеллектуальной собственности для указанного прототипа (Unable to perform intellectual property check, please try again). Учётные записи Enterprise с включённой фильтрацией интеллектуальной собственности при этой проверке блокируются по принципу «отказ при неопределённости»; списание средств не производится — повторите запрос.

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"
}
GET/openapi/creative-lab/fidget-pixel/v1/(prototype|build)/:id

Получить задачу Fidget Pixel

Получить задачу прототипа или сборки по действительному id задачи. Путь URL должен соответствовать стадии задачи — если задача сборки запрашивается через /prototype/:id, возвращается 404, и наоборот.

Обратитесь к разделам Объект задачи прототипа Fidget Pixel и Объект задачи сборки Fidget Pixel, чтобы узнать структуру ответа.

Параметры

  • Name
    id
    Type
    path
    Description

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

Возвращаемые значения

Ответ содержит объект задачи fidget pixel. Структура зависит от того, какая стадия была запрошена.

Режимы сбоя

  • Name
    400 - Bad Request
    Description

    id не является допустимым UUID (Invalid ID).

  • Name
    403 - Forbidden
    Description

    Изображение задачи было отмечено модерацией на предмет нарушения прав интеллектуальной собственности. Блокируются только Enterprise-аккаунты с включённой фильтрацией по интеллектуальной собственности.

  • Name
    404 - Not Found
    Description

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

  • Name
    500 - Internal Server Error
    Description

    Не удалось выполнить проверку на нарушение прав интеллектуальной собственности (Unable to perform intellectual property check, please try again); для Enterprise-аккаунтов с включённой фильтрацией по интеллектуальной собственности применяется отказ по умолчанию (fail closed). Повторите запрос.

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=***"
  }
}
DELETE/openapi/creative-lab/fidget-pixel/v1/(prototype|build)/:id

Удаление задачи Fidget Pixel

Отменяет задачу fidget pixel. Если задача всё ещё находится в статусе PENDING, кредиты, списанные при создании, возвращаются. Задачи, уже находящиеся в статусе IN_PROGRESS, отменяются без возврата средств (воркер, возможно, уже расходует ресурсы). Задачи, уже достигшие финального статуса (SUCCEEDED, FAILED, CANCELED), отменить нельзя.

Путь URL должен соответствовать стадии задачи — вызов DELETE на /prototype/:buildId возвращает 404.

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

  • Name
    id
    Type
    path
    Description

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

Возвращаемое значение

В случае успеха возвращает 204 No Content с пустым телом ответа.

Режимы сбоя

  • Name
    400 - Bad Request
    Description

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

    • Недопустимый ID: id не является допустимым UUID.
    • Финальный статус: задача уже находится в статусе SUCCEEDED, FAILED или CANCELED и не может быть отменена.
  • Name
    404 - Not Found
    Description

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

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).
GET/openapi/creative-lab/fidget-pixel/v1/(prototype|build)/:id/stream

Стрим задачи Fidget Pixel

Транслирует обновления задачи fidget pixel в реальном времени через Server-Sent Events (SSE). Путь URL должен соответствовать этапу задачи — открытие потока по адресу /prototype/:buildId/stream приводит к отправке единственной полезной нагрузки event: error со status_code: 404, после чего поток закрывается; некорректный id приводит к тому же результату со status_code: 400 (Invalid ID).

Параметры

  • Name
    id
    Type
    path
    Description

    Уникальный идентификатор задачи fidget pixel для стриминга.

Возвращает

Возвращает поток объектов задач Fidget Pixel Prototype или Fidget Pixel Build в виде Server-Sent Events. Каждый кадр содержит полный объект задачи для данного этапа — в той же форме, что возвращает эндпоинт Get, — поэтому пока задача находится в статусе PENDING или IN_PROGRESS, поля вывода просто ещё не заполнены (null, [] или {}), а finished_at равно null.

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=***"
  }
}
GET/openapi/creative-lab/fidget-pixel/v1/(prototype|build)

List Fidget Pixel Tasks

Получите постраничный список ваших задач fidget pixel для одного этапа. Путь 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

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

  • Name
    sort_by
    Type
    string
    по умолчанию -created_at
    Description

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

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

Возвращает

Возвращает постраничный список объектов задач для конкретного этапа — либо объект задачи прототипа fidget pixel при запросе списка /prototype, либо объект задачи сборки fidget pixel при запросе списка /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=***"
    ]
  }
]

Объект задачи прототипа Fidget Pixel

Объект задачи прототипа Fidget Pixel — это рабочая единица, которую Meshy отслеживает для превращения исходной фотографии в изображение в стиле пиксель-арт. Результат этого этапа передаётся в этап сборки через input_task_id.

Свойства

  • Name
    id
    Type
    string
    Description

    Уникальный идентификатор задачи. Хотя в качестве деталей реализации мы используем k-сортируемый UUID для идентификаторов задач, вам не следует делать никаких предположений о формате id.

  • Name
    type
    Type
    string
    Description

    Тип задачи. Значение — creative-lab-fidget-pixel-prototype.

  • Name
    name
    Type
    string
    Description

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

  • Name
    status
    Type
    string
    Description

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

  • Name
    progress
    Type
    integer
    Description

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

  • Name
    created_at
    Type
    timestamp
    Description

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

    Временная метка представляет собой количество миллисекунд, прошедших с 1 января 1970 года UTC, в соответствии со стандартом RFC 3339. Например, пятница, 1 сентября 2023 года, 12:00:00 по Гринвичу представляется как 1693569600000. Это применимо ко всем временным меткам в Meshy API.

  • Name
    started_at
    Type
    timestamp
    Description

    Временная метка начала выполнения задачи, в миллисекундах. Если задача ещё не начата, это свойство будет равно null.

  • Name
    finished_at
    Type
    timestamp
    Description

    Временная метка завершения задачи, в миллисекундах. Если задача ещё не завершена, это свойство будет равно null.

  • Name
    expires_at
    Type
    timestamp
    Description

    Временная метка истечения срока действия результата задачи, в миллисекундах — 3 дня после завершения задачи. Корпоративные аккаунты хранят результаты API бессрочно (см. Хранение ресурсов); для них эта временная метка устанавливается примерно на 100 лет вперёд.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Количество предшествующих задач.

    Значение этого поля имеет смысл только если статус задачи — PENDING.

  • Name
    task_error
    Type
    object
    Description

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

  • Name
    consumed_credits
    Type
    integer
    Description

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

  • Name
    image_urls
    Type
    array of strings
    Description

    Ссылки для скачивания изображения в стиле пиксель-арт, сгенерированного этой задачей прототипа. В настоящее время API всегда возвращает ровно одно изображение; поле представлено массивом, чтобы в будущих версиях можно было выводить несколько вариантов без обратной несовместимости. Пусто, пока задача не достигнет статуса SUCCEEDED.

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

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=***"
  ]
}

Объект задачи сборки Fidget Pixel

Объект задачи сборки Fidget Pixel — это единица работы, отслеживаемая Meshy для генерации печатаемых деталей из успешно завершённой прототипной задачи. Сборка сэмплирует пиксель-арт изображение прототипа на запрошенную сетку и публикует единый 3MF-файл с цветовой маркировкой.

Свойства

  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

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

  • Name
    name
    Type
    string
    Description

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

  • Name
    status
    Type
    string
    Description

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

  • Name
    progress
    Type
    integer
    Description

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

  • Name
    created_at
    Type
    timestamp
    Description

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

  • Name
    started_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

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

  • Name
    expires_at
    Type
    timestamp
    Description

    Временная метка истечения срока действия результата задачи, в миллисекундах — 3 дня после завершения задачи. Корпоративные аккаунты хранят результаты API бессрочно (см. Хранение ресурсов); для них эта временная метка устанавливается на срок около 100 лет вперёд.

  • Name
    preceding_tasks
    Type
    integer
    Description

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

  • Name
    task_error
    Type
    object
    Description

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

  • Name
    consumed_credits
    Type
    integer
    Description

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

  • Name
    model_urls
    Type
    object
    Description

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

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

    • Name
      3mf
      Type
      string
      Description

      Ссылка для скачивания файла 3MF. Один объект на деталь, каждый помечен своим цветом палитры, так что многофиламентный слайсер назначает филаменты по цвету. Присутствует, когда output.format был 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=***"
  }
}

Полный пример

Полный процесс: создать прототип из фотографии, опрашивать его до статуса SUCCEEDED, создать сборку на его основе, опрашивать сборку до статуса SUCCEEDED, а затем скачать 3MF из model_urls.

Прототип обычно завершается за несколько минут; сборка, как правило, выполняется менее чем за минуту. В реальной интеграции вы бы показали пользователю значение 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"