Creative Lab — API фигурки

Превратите исходное фото в коллекционную 3D-фигурку в стиле чиби за два этапа: прототип генерирует стилизованное концепт-изображение на основе вашего входного фото, затем сборка превращает это концепт-изображение в 3D-модель с текстурами. Эти два этапа связаны через input_task_id.

  • POST /openapi/creative-lab/figure/v1/prototype
  • POST /openapi/creative-lab/figure/v1/build


POST/openapi/creative-lab/figure/v1/prototype

Создать задачу прототипа фигурки

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

Параметры

  • 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 в эндпоинт сборки как input_task_id.

Возможные ошибки

  • Name
    400 - Bad Request
    Description

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

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

    Аутентификация не удалась. Проверьте ваш API-ключ.

  • Name
    402 - Payment Required
    Description

    Недостаточно кредитов для выполнения этой задачи.

  • Name
    429 - Too Many Requests
    Description

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

Request

POST
/openapi/creative-lab/figure/v1/prototype
# Stage 1: generate a chibi-style concept image
curl https://api.meshy.ai/openapi/creative-lab/figure/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 portrait, then generate the prototype image used by the build stage.
Source portrait used as the Creative Lab Figure input
Prototype input
Chibi-style figurine prototype image generated from the source photo
Prototype output

POST/openapi/creative-lab/figure/v1/build

Создать задачу сборки фигурки

Сгенерируйте финальную 3D-фигурку с текстурами из успешно выполненной задачи прототипа. Сборка запускает тот же конвейер преобразования изображения в 3D, что и Изображение в 3D, поэтому формат объекта ответа и список выходных URL полностью совпадают. См. Объект задачи сборки фигурки для структуры ответа.

Параметры

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

    ID задачи прототипа, созданной через этот же OpenAPI-эндпоинт. Прототип должен быть создан с тем же API-ключом, должен достичь SUCCEEDED и должен создать ровно одно изображение-кандидат.

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

  • Name
    name
    Type
    string
    Description

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

Возвращает

Свойство result в ответе содержит id задачи только что созданной задачи сборки фигурки. Опросите эндпоинт Получить задачу или подпишитесь на поток, пока задача не достигнет SUCCEEDED, затем загрузите GLB с текстурами из model_urls.glb (или пару OBJ + MTL из model_urls.obj и model_urls.mtl, если ваш последующий конвейер предпочитает OBJ).

Сценарии ошибок

  • Name
    400 - Bad Request
    Description

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

    • Отсутствующий параметр: требуется input_task_id.
    • Недопустимый UUID: input_task_id не является допустимым UUID.
    • Родительская задача не выполнена успешно: указанная задача прототипа еще не достигла SUCCEEDED.
    • Нет кандидата: задача прототипа выполнена успешно, но не создала изображение-кандидат.
  • Name
    401 - Unauthorized
    Description

    Аутентификация не удалась. Проверьте свой API-ключ.

  • Name
    402 - Payment Required
    Description

    Недостаточно кредитов для выполнения этой задачи.

  • Name
    404 - Not Found
    Description

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

  • Name
    429 - Too Many Requests
    Description

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

Request

POST
/openapi/creative-lab/figure/v1/build
# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

Response

{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}
Build example
The build task turns the selected prototype image into a downloadable textured 3D model.
Предпросмотр модели сборки фигурки Creative Lab
Build model preview

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

Получить задачу фигурки

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

См. Объект задачи прототипа фигурки и Объект задачи сборки фигурки, чтобы узнать формы ответа.

Параметры

  • Name
    id
    Type
    path
    Description

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

Возвращает

Ответ содержит объект задачи фигурки. Форма зависит от того, какой этап был запрошен.

Request

GET
/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578
# Prototype
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-figure-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-figure-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 20,
  "prompt": "",
  "negative_prompt": "",
  "texture_prompt": "",
  "texture_image_url": "",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?Expires=***"
    }
  ]
}

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

Удаление задачи фигурки

Отменить задачу фигурки. Если задача все еще находится в статусе PENDING, кредиты, израсходованные при создании, возвращаются. Задачи, которые уже находятся в статусе IN_PROGRESS, отменяются без возврата (worker, возможно, уже расходует ресурсы). Задачи, которые уже достигли терминального состояния (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.

Request

DELETE
/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

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

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

Потоковая передача задачи фигурки

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

Параметры

  • Name
    id
    Type
    path
    Description

    Уникальный идентификатор задачи фигурки для потоковой передачи.

Возвращает

Возвращает поток объектов задач прототипа фигурки или сборки фигурки в виде Server-Sent Events. Для задач PENDING или IN_PROGRESS поток ответа будет включать только необходимые поля progress и status.

Request

GET
/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream
curl -N https://api.meshy.ai/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-figure-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 20,
  "prompt": "",
  "negative_prompt": "",
  "texture_prompt": "",
  "texture_image_url": "",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?Expires=***"
    }
  ]
}

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

Список задач фигурок

Получите список с пагинацией ваших задач фигурок для одного этапа. Путь URL выбирает этап — /prototype возвращает задачи prototype; /build возвращает задачи build. Задачи с другого этапа не включаются ни в один из ответов.

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

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

    Либо prototype, либо build. Коллекция возвращает только задачи, этап которых соответствует URL — запрос /prototype никогда не возвращает задачи build и наоборот.

Параметры запроса

  • 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: Сортировка по времени создания в порядке убывания.

Возвращает

Возвращает список с пагинацией объектов задач для соответствующего этапа — либо объект задачи prototype фигурки при получении списка /prototype, либо объект задачи build фигурки при получении списка /build.

Request

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

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

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-figure-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123486000,
    "expires_at": 1729382686000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

Объект задачи прототипа фигурки

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

Свойства

  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

    Тип задачи. Значение — creative-lab-figure-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

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

  • 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

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

  • Name
    task_error
    Type
    object
    Description

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

  • Name
    consumed_credits
    Type
    integer
    Description

    Количество кредитов, consumed_credits этой задачей. Присутствует, когда статус задачи — PENDING, IN_PROGRESS или SUCCEEDED. Возвращает 0 для задач FAILED (кредиты возвращаются при сбое).

  • Name
    image_urls
    Type
    array of strings
    Description

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

Example Figure Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-figure-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Объект задачи создания фигурки

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

Свойства

  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

    Тип задачи. Значение — creative-lab-figure-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
    prompt
    Type
    string
    Description

    Всегда пусто для сборки фигурки. Присутствует для совместимости между эндпоинтами с общей структурой V2ImageTo3DTaskResponse, используемой в Изображение в 3D.

  • Name
    negative_prompt
    Type
    string
    Description

    Всегда пусто для сборки фигурки. Присутствует для совместимости между эндпоинтами.

  • Name
    texture_prompt
    Type
    string
    Description

    Всегда пусто для сборки фигурки. Присутствует для совместимости между эндпоинтами.

  • Name
    texture_image_url
    Type
    string
    Description

    Всегда пусто для сборки фигурки. Присутствует для совместимости между эндпоинтами.

  • Name
    model_urls
    Type
    object
    Description

    Скачиваемые URL для сгенерированной 3D-модели. Сборка фигурки выдает текстурированный GLB, а также пару OBJ + MTL для пайплайнов, предпочитающих Wavefront OBJ. Структура поля соответствует объекту Изображение в 3D model_urls, поэтому будущие добавления форматов можно будет встроить без критического изменения.

    • Name
      glb
      Type
      string
      Description

      Скачиваемый URL текстурированного файла GLB.

    • Name
      obj
      Type
      string
      Description

      Скачиваемый URL файла Wavefront OBJ (геометрия + UV).

    • Name
      mtl
      Type
      string
      Description

      Скачиваемый URL сопутствующего файлу OBJ файла материала MTL. Используйте вместе с obj и записью из texture_urls[0].base_color.

  • Name
    thumbnail_url
    Type
    string
    Description

    Скачиваемый URL изображения миниатюры файла модели.

  • Name
    texture_urls
    Type
    array
    Description

    Массив объектов URL текстур, сгенерированных этой задачей. В настоящее время содержит один объект с картой базового цвета.

    • Name
      base_color
      Type
      string
      Description

      Скачиваемый URL изображения карты базового цвета.

Example Figure Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-figure-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 20,
  "prompt": "",
  "negative_prompt": "",
  "texture_prompt": "",
  "texture_image_url": "",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?Expires=***"
    }
  ]
}