Text to 3D API

Генерируйте 3D-модели из текстовых запросов в своём собственном приложении.

Текст в 3D работает в два этапа. Сначала создайте задачу preview (mode: "preview") для генерации 3D-сетки без текстуры, чтобы вы могли проверить форму. Затем отправьте ID успешной задачи preview в задачу refine (mode: "refine"), чтобы нанести текстуру на сетку. Оба этапа используют один и тот же эндпоинт.

POST/openapi/v2/text-to-3d

Создать задачу предпросмотра Text to 3D

Создаёт задачу предпросмотра Text to 3D, которая генерирует нетекстурированную 3D-сетку (только геометрию) из текстового prompt. Это первый шаг двухэтапного процесса. После успешного завершения предпросмотра отправьте его ID задачи в задачу refine, чтобы наложить текстуру на сетку. См. Создать задачу refine Text to 3D. Полную схему ответа см. в разделе Объект задачи Text to 3D.

Задача выполняется в фоновом режиме. Информацию о том, сколько обычно занимает выполнение задачи, см. в разделе Время обработки.

Request

POST

/openapi/v2/text-to-3d

# Simple preview with required params only
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a monster mask"
}'

# Preview with Ultra 4K geometry, remesh, and A-pose
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a futuristic robot warrior",
  "ai_model": "meshy-7.1",
  "geometry_resolution": "4k",
  "should_remesh": true,
  "target_polycount": 100000,
  "pose_mode": "a-pose",
  "target_formats": ["glb"]
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Параметры

Name
mode
Type
string
Обязательный
Description
Шаг двухэтапного процесса. Отправьте preview, чтобы создать задачу предпросмотра.
Name
prompt
Type
string
Обязательный
Description
Текст, описывающий объект для генерации, до 800 символов. Более длинный текст возвращает 400.
Name
model_type
Type
string
по умолчанию standard
Description
Тип генерируемой 3D-сетки.
Доступные значения:
- standard: высокодетализированная 3D-сетка
- smart-topology: сетка Smart Topology. Выберите модель с помощью ai_model (meshy-t2 или meshy-t2.5).
При smart-topology Meshy игнорирует should_remesh и decimation_mode и принимает только topology: triangle.
Name
ai_model
Type
string
по умолчанию latest
Description
AI-модель, генерирующая 3D-модель. Доступные значения зависят от model_type.
Стандартные модели (model_type: standard):
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest: Meshy 7.1
- meshy-7 (устаревшее): отправляйте вместо неё meshy-7.1
Модели Smart Topology (model_type: smart-topology):
- meshy-t2: более чистая topology, изначально разделённые части, вывод в виде треугольников и количество граней, задаваемое через target_polycount
- meshy-t2.5 (по умолчанию): более чёткая детализация для игровых ассетов, вывод в виде треугольников и количество граней, задаваемое через target_polycount
См. Модели, чтобы узнать, какая модель подходит для вашего проекта, например игрового персонажа или 3D-печати.
Name
geometry_resolution
Type
string
по умолчанию standard
Description
Проход генерации геометрии. Применяется только к задачам предпросмотра. Запрос refine с этим параметром возвращает 400.
Доступные значения:
- standard
- 2k: запускает Ultra-проход при 2048³
- 4k: запускает Ultra-проход при 4096³ для более тонкой детализации поверхности
2k требует meshy-7.1, latest или устаревшую meshy-7. 4k требует meshy-7.1 или latest. Другие модели возвращают 400.
Name
ultra_mode
Type
boolean
⚠ устаревший
по умолчанию false
Description
Отправляйте вместо этого geometry_resolution. ultra_mode: true эквивалентно geometry_resolution: "2k".
Name
should_remesh
Type
boolean
по умолчанию true (meshy-6-lite), false (other models)
Description
Нужно ли выполнять ремешинг модели после генерации. Для получения 3D-модели максимального качества отправьте false.

Применяется только когда should_remesh = true

Name
topology
Type
string
по умолчанию triangle
Description
Тип граней ремешированной модели.
Доступные значения:
- quad: сетка с преобладанием четырёхугольников
- triangle: децимированная треугольная сетка
Вывод Smart Topology — только треугольный. Отправка quad с ai_model meshy-t2 или meshy-t2.5 возвращает 400.
Name
decimation_mode
Type
integer
Description
Адаптивное количество граней, по уровню. Когда вы задаёте этот параметр, Meshy игнорирует target_polycount.
Доступные значения:
- 1: ultra
- 2: high
- 3: medium
- 4: low

Name
target_polycount
Type
integer
Description
Целевое количество граней. Итоговый результат может отличаться от целевого значения в зависимости от геометрии. Этот параметр применяется в двух отдельных случаях:
- Ремешинг: с should_remesh: true для модели standard. Meshy выполняет ремешинг (децимацию) сетки примерно до этого количества. Если вы задали decimation_mode, Meshy использует его и игнорирует target_polycount.
- Smart Topology: с model_type: smart-topology и ai_model meshy-t2 или meshy-t2.5. Meshy генерирует модель с этим количеством граней напрямую. Ремешинг не выполняется, и should_remesh не требуется.
В следующей таблице показаны диапазон и значение по умолчанию для каждого случая:
Случай Диапазон По умолчанию
Ремешинг 100 – 300000 30000
meshy-t2 100 – 15000 4000
meshy-t2.5 100 – 30000 15000
Значение вне диапазона возвращает 400.
Для низкополигонального игрового ассета используйте модель Smart Topology вместо ремешинга стандартной модели. См. Модели.

Случай	Диапазон	По умолчанию
Ремешинг	`100` – `300000`	`30000`
`meshy-t2`	`100` – `15000`	`4000`
`meshy-t2.5`	`100` – `30000`	`15000`

Name
symmetry_mode
Type
string
⚠ устаревший
по умолчанию auto
Description
Не указывайте этот параметр. Он не влияет на результат.
Доступные значения:
- off: отключает симметрию
- auto: применяет симметрию на основе входной геометрии
- on: принудительно применяет симметрию при генерации
Name
pose_mode
Type
string
по умолчанию ""
Description
Поза генерируемой модели.
Доступные значения:
- a-pose: поза A
- t-pose: поза T
- "" (пустая строка): без конкретной позы
Name
is_a_t_pose
Type
boolean
⚠ устаревший
по умолчанию false
Description
Отправляйте вместо этого pose_mode. Нужно ли генерировать модель в позе A или позе T.
Name
art_style
Type
string
⚠ устаревший
по умолчанию realistic
Description
Не указывайте этот параметр. Meshy его игнорирует.
Name
moderation
Type
boolean
по умолчанию false
Description
Проверять ли prompt на вредоносный контент перед генерацией. Если Meshy обнаружит вредоносный контент, запрос вернёт 400, и Meshy не создаст задачу.
Name
target_formats
Type
string[]
Description
Форматы файлов для генерации. Meshy генерирует и возвращает только эти форматы, что может сократить время выполнения задачи. Если не указать этот параметр, Meshy сгенерирует все форматы, кроме 3mf, который генерируется только по отдельному запросу.
Доступные значения:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
по умолчанию false
Description
Рендерить ли также предпросмотр с прозрачным фоном (RGBA), который возвращается в alpha_thumbnail_url при получении задачи. thumbnail_url при этом не меняется.
Name
auto_size
Type
boolean
по умолчанию false
Description
Оценивать ли реальную высоту объекта с помощью AI-зрения и изменять размер модели в соответствии с ней. Meshy помещает начало координат внизу, если не задано origin_at.

Применяется только когда auto_size = true

Name
origin_at
Type
string
по умолчанию bottom
Description
Где разместить начало координат модели: bottom или center.

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

Поле result ответа содержит ID новой задачи Text to 3D.

Режимы сбоя

Name
400 - Bad Request
Description
Запрос не может быть выполнен. Сообщение об ошибке указывает, какая проблема была обнаружена. Например:
- Отсутствует параметр: отсутствует обязательный параметр, например prompt или mode.
- Слишком длинный prompt: prompt превышает лимит символов.
- Неподдерживаемая модель для Ultra: geometry_resolution имеет значение 2k или 4k при ai_model, которая не поддерживает этот режим.
Исправьте запрос и отправьте его снова. См. Ошибки.
Name
401 - Unauthorized
Description
API-ключ отсутствует или недействителен. Проверьте заголовок Authorization.
Name
402 - Payment Required
Description
Например:
- Недостаточно кредитов: на аккаунте недостаточно кредитов для этой задачи, либо аккаунт достиг лимита кредитов. Проверьте баланс кредитов и повторите попытку.
- Бесплатный план: для создания задачи требуется платный план. Обновите план в настройках подписки и повторите попытку.
Name
403 - Forbidden
Description
Модерация контента заблокировала prompt или входное изображение. Измените входные данные и повторите попытку.
Name
429 - Too Many Requests
Description
Вы превысили ограничение частоты запросов. Подождите и повторите попытку. См. Ограничения частоты запросов.

POST/openapi/v2/text-to-3d

Создание задачи refine для Текст в 3D

Создаёт задачу refine для Текст в 3D, которая текстурирует сетку завершённой задачи preview. Отправьте ID успешной задачи preview в параметре preview_task_id. См. Создание задачи preview для Текст в 3D. Это второй шаг двухэтапного процесса.

Задача выполняется в фоновом режиме. О том, сколько обычно занимает выполнение задачи, см. Время обработки.

Request

POST

/openapi/v2/text-to-3d

# Basic refine task
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "enable_pbr": true
}'

# Refine with auto-size and GLB format
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "target_formats": ["glb"],
  "auto_size": true
}'

# Refine with Meshy N1 from the preview's stored reference image
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "ai_model": "meshy-n1"
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Параметры

Name
mode
Type
string
Обязательный
Description
Шаг двухэтапного процесса. Отправьте refine, чтобы создать задачу refine.
Name
preview_task_id
Type
string
Обязательный
Description
ID задачи preview, которую нужно текстурировать. Задача preview должна иметь статус SUCCEEDED.
Name
enable_pbr
Type
boolean
по умолчанию false
Description
Генерировать ли также PBR-карты (metallic, roughness и normal) вместе с базовым цветом.
При ai_model meshy-6 Meshy также генерирует emission-карту, за исключением случая texture_resolution: 8k. Модели meshy-6-lite, meshy-7, meshy-7.1 и latest не генерируют emission-карту. Это же относится и к refine задачи preview meshy-t2 или meshy-t2.5, для которой не задан ai_model. При ai_model: meshy-n1 значение true приводит к ошибке 400.
Name
texture_resolution
Type
string
по умолчанию 2k
Description
Разрешение текстуры базового цвета. Применяется только к задачам refine. Если указать этот параметр для preview, вернётся 400.
Доступные значения:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
Более высокое разрешение передаёт больше деталей поверхности. Для 4k и 8k требуется ai_model meshy-6, meshy-7.1 или latest. При meshy-n1 они возвращают 400. При 8k Meshy не генерирует emission-карту.
Name
hd_texture
Type
boolean
⚠ устаревший
по умолчанию false
Description
Используйте вместо этого texture_resolution. hd_texture: true эквивалентно texture_resolution: "4k". Если отправить оба параметра, Meshy использует texture_resolution.
Name
texture_prompt
Type
string
Description
Текст, направляющий текстурирование, до 800 символов. Более длинный текст приводит к ошибке 400. Отправьте либо texture_prompt, либо texture_image_url, но не оба сразу. Если отправить оба, Meshy использует texture_prompt. При ai_model: meshy-n1 отправка этого параметра возвращает 400.
Name
texture_image_url
Type
string
Description
2D-изображение, направляющее текстурирование, в виде публичного URL или base64-кодированного Data URI, например data:image/jpeg;base64,<ваши base64-закодированные данные изображения>.
Изображение должно быть файлом .jpg, .jpeg, .png или .webp размером не более 20 МБ, не менее 32 пикселей по каждой стороне и не более 178 956 970 пикселей (ширина × высота).
При ai_model: meshy-n1 Meshy текстурирует, используя это изображение как вид спереди.
Текстурирование по изображению может работать плохо, если форма на изображении сильно отличается от модели.
Name
ai_model
Type
string
по умолчанию наследуется из задачи preview
Description
AI-модель, которая текстурирует сетку.
Доступные значения:
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest: Meshy 7.1
- meshy-n1: 2K-текстура базового цвета только по референсному изображению. Без текстового prompt, без PBR-карт, без 4K или 8K.
- meshy-7 (устаревшее): используйте вместо этого meshy-7.1
Не указывайте параметр, чтобы использовать модель задачи preview, тогда preview и её refine будут выполняться на одной и той же модели от начала до конца. Отправьте значение, чтобы переопределить это поведение. Явное указание latest разрешается так же, как и для задачи preview, поэтому preview с latest и её refine с latest всегда используют одну и ту же модель текстурирования.
При meshy-n1 Meshy текстурирует по texture_image_url. Если этот параметр не указан, Meshy использует референсное изображение, сохранённое в preview с meshy-7.1 или latest. Любая другая preview возвращает 400, если не отправлен texture_image_url. Preview может содержать не более 7 999 999 треугольников. Preview, подвергнутая remesh в четырёхугольники, возвращает 400.
Name
moderation
Type
boolean
по умолчанию false
Description
Проверять ли texture_prompt и texture_image_url на наличие вредоносного контента перед генерацией. Если Meshy обнаруживает вредоносный контент, запрос возвращает 400, и Meshy не создаёт задачу.
Name
remove_lighting
Type
boolean
по умолчанию true
Description
Удалять ли блики и тени из текстуры базового цвета. Более чистый результат лучше работает при пользовательском освещении.
Действует только при ai_model, равном meshy-6. Модели meshy-7.1 и latest принимают этот параметр, но игнорируют его, как и refine задачи preview meshy-t2 или meshy-t2.5, для которой не задан ai_model. Отправка этого параметра с meshy-6-lite возвращает 400. При meshy-n1 значение true возвращает 400.
Name
target_formats
Type
string[]
Description
Форматы файлов для генерации. Meshy генерирует и возвращает только эти форматы, что может сократить время выполнения задачи. Если не указать параметр, Meshy генерирует все форматы, кроме 3mf, который генерируется только по запросу.
Доступные значения:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
по умолчанию false
Description
Рендерить ли также превью с прозрачным фоном (RGBA), которое возвращается в alpha_thumbnail_url при получении задачи. thumbnail_url при этом не изменяется.
Name
auto_size
Type
boolean
по умолчанию false
Description
Оценивать ли реальную высоту объекта с помощью AI-зрения и масштабировать модель под неё. Meshy помещает начало координат внизу, если не задан origin_at.

Применяется только когда auto_size = true

Name
origin_at
Type
string
по умолчанию bottom
Description
Куда поместить начало координат модели: bottom или center.

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

Поле result в ответе содержит ID новой задачи Текст в 3D.

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

Name
400 - Bad Request
Description
Запрос не может быть выполнен. Сообщение об ошибке указывает, в чём проблема. Например:
- Недействительный ID задачи: preview_task_id недействителен или не соответствует ни одной из ваших задач preview.
- Задача не готова: Задача preview ещё не завершилась успешно.
- Несоответствие моделей: AI-модель задачи preview несовместима с запрошенной моделью refine.
- Неподдерживаемая модель для remove_lighting: remove_lighting был отправлен с ai_model: "meshy-6-lite".
- Нет референсного изображения для Meshy N1: ai_model: meshy-n1 был отправлен без texture_image_url, а у preview нет референсного изображения, которое может использовать Meshy N1. Отправьте texture_image_url.
- Четырёхугольная preview для Meshy N1: ai_model: meshy-n1 был отправлен для preview, подвергнутой remesh в четырёхугольники. Выполните refine с другим ai_model.
- Слишком много треугольников для Meshy N1: При ai_model: meshy-n1 preview содержит более 7 999 999 треугольников. Выполните refine с другим ai_model.
- Неподдерживаемая опция для Meshy N1: ai_model: meshy-n1 был отправлен вместе с одной из следующих опций:
  - texture_prompt
  - enable_pbr: true
  - texture_resolution со значением 4k или 8k
  - hd_texture: true без texture_resolution
  - remove_lighting: true
Исправьте запрос и отправьте его снова. См. Ошибки.
Name
401 - Unauthorized
Description
API-ключ отсутствует или недействителен. Проверьте заголовок Authorization.
Name
402 - Payment Required
Description
Например:
- Недостаточно кредитов: На счёте недостаточно кредитов для этой задачи, либо достигнут лимит кредитов. Проверьте баланс кредитов и повторите попытку.
- Бесплатный план: Для создания задачи требуется платный план. Повысьте план в настройках подписки и повторите попытку.
Name
403 - Forbidden
Description
Модерация контента заблокировала prompt или входное изображение. Измените входные данные и повторите попытку.
Name
429 - Too Many Requests
Description
Вы превысили ограничение частоты запросов. Подождите и повторите попытку. См. Ограничения частоты запросов.

GET/openapi/v2/text-to-3d/:id

Получить задачу Текст в 3D

Возвращает задачу Текст в 3D по её ID. Работает как для задач preview, так и для задач refine.

Request

GET

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "prompt": "a monster mask",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 20
}

Параметры

Name
id
Type
path
Description
ID задачи из ответа на создание.

Возвращает

Объект задачи Текст в 3D.

Примеры

В таблице ниже показана примерная модель для каждого mode.

Mode	Пример модели
Preview
Refine

DELETE/openapi/v2/text-to-3d/:id

Удаление задачи Текст в 3D

Безвозвратно удаляет задачу Текст в 3D, включая её модели и данные. Отменить удаление нельзя.

Request

DELETE

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

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

Name
id
Type
path
Description
ID задачи для удаления.

Статус задачи

Удаление задачи со статусом PENDING возвращает кредиты, потраченные на её создание.

Задачу со статусом IN_PROGRESS удалить нельзя. Запрос вернёт 409 Conflict, а задача продолжит выполняться. Meshy не возвращает кредиты за задачу, которая уже начала выполняться, поэтому её удаление означало бы потерю и кредитов, и результата. Дождитесь, пока она перейдёт в статус SUCCEEDED, FAILED или CANCELED, и только затем удаляйте.

Удаление задачи в конечном статусе (SUCCEEDED, FAILED или CANCELED) не возвращает потраченные на неё кредиты.

Возвращает

200 OK, когда задача удалена, или 409 Conflict, когда задача имеет статус IN_PROGRESS.

GET/openapi/v2/text-to-3d

Список задач Текст в 3D

Возвращает список ваших задач Текст в 3D.

Request

GET

/openapi/v2/text-to-3d

curl https://api.meshy.ai/openapi/v2/text-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-3d-preview",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
      "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "prompt": "a monster mask",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
      }
    ],
    "preceding_tasks": 0,
    "task_error": null,

    "consumed_credits": 20
  }
]

Параметры

Name
page_num
Type
integer
по умолчанию 1
Description
Номер страницы для возврата, до 255. Большее значение вернёт 400.
Name
page_size
Type
integer
по умолчанию 10
Description
Количество задач на странице, до 100.
Name
sort_by
Type
string
Description
Порядок сортировки.
Доступные значения:
- +created_at: сначала старые
- -created_at: сначала новые

Возвращает

Постраничный список объектов задач Текст в 3D.

GET/openapi/v2/text-to-3d/:id/stream

Поток обновлений задачи «Текст в 3D»

Передаёт обновления задачи «Текст в 3D» в виде Server-Sent Events (SSE).

Request

GET

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// These examples are shortened. Each event holds the full task object.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
},
"texture_urls": [
  {
    "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
    "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
    "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
    "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
    "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
  }
],
"preceding_tasks": 0,
"task_error": null,

"consumed_credits": 20
}

Параметры

Name
id
Type
path
Description
ID задачи из ответа при создании.

Возвращает

Поток объектов задачи «Текст в 3D» в виде Server-Sent Events.

Каждое событие содержит полный объект задачи — в том же формате, что возвращает эндпоинт Get. Пока задача имеет статус PENDING или IN_PROGRESS, поля с результатом ещё не заполнены.

Объект задачи Text to 3D

Объект задачи Text to 3D описывает одну задачу, которая генерирует 3D-модель на основе текстового prompt. Он хранит статус, progress и файлы модели после успешного завершения задачи. У Text to 3D есть два этапа: preview и refine. Задача preview создаёт 3D-модель только с сеткой, а задача refine создаёт текстурированную 3D-модель на основе результата preview.

Свойства

Example Text to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  },
  "prompt": "a monster mask",
  "texture_prompt": "green slimy skin with scales and warts",
  "texture_image_url": "",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 20
}

Name
id
Type
string
Description
ID задачи. Воспринимайте его как непрозрачную строку и не полагайтесь на его формат.
Name
type
Type
string
Description
Тип задачи: text-to-3d-preview для задачи preview или text-to-3d-refine для задачи refine.
Name
model_urls
Type
object
Description
URL для скачивания сгенерированной 3D-модели, по одному на каждый формат файла. Если задача не сгенерировала файл в определённом формате, для него нет ключа — вместо пустой строки.
- Name
  glb
  Type
  string
  Description
  Файл GLB.
- Name
  fbx
  Type
  string
  Description
  Файл FBX.
- Name
  usdz
  Type
  string
  Description
  Файл USDZ.
- Name
  obj
  Type
  string
  Description
  Файл OBJ.
- Name
  mtl
  Type
  string
  Description
  Файл MTL.
- Name
  stl
  Type
  string
  Description
  Файл STL.
- Name
  3mf
  Type
  string
  Description
  Файл 3MF. Присутствует только если target_formats включает 3mf.
Name
prompt
Type
string
Description
prompt, который вы отправили для создания задачи, без изменений.
Name
texture_prompt
Type
string
Description
Текстовый prompt, который вы отправили для управления текстурированием на этапе refine.
Name
ultra_mode
Type
boolean
⚠ устаревший
Description
Используйте вместо этого geometry_resolution.
Name
geometry_resolution
Type
string
Description
Уровень Ultra, с которым выполнялась задача preview: 2k или 4k. Поле отсутствует для standard.
Name
texture_image_url
Type
string
Description
URL для скачивания изображения, которое вы отправили для управления текстурированием.
Name
thumbnail_url
Type
string
Description
URL для скачивания миниатюры 3D-модели.
Name
alpha_thumbnail_url
Type
string
Description
URL для скачивания версии thumbnail_url с прозрачным фоном (RGBA). Присутствует только если вы создали задачу с alpha_thumbnail: true, и Meshy отрендерил прозрачный предпросмотр.
Name
progress
Type
integer
Description
Насколько выполнена задача, в процентах. Значение 0, пока задача не началась, и 100, когда она завершена успешно.
Name
started_at
Type
timestamp
Description
Время начала задачи, в миллисекундах Unix. Значение 0, пока задача не началась.
Name
created_at
Type
timestamp
Description
Время создания задачи, в миллисекундах Unix.
Name
finished_at
Type
timestamp
Description
Время завершения задачи, в миллисекундах Unix. Значение 0, пока задача не завершена.
Name
status
Type
string
Description
Статус задачи: одно из значений PENDING, IN_PROGRESS, SUCCEEDED, FAILED или CANCELED.
Name
texture_urls
Type
array
Description
URL для скачивания сгенерированных карт текстур, в виде массива объектов. Обычно содержит один объект. Каждый объект содержит следующие поля:
- Name
  base_color
  Type
  string
  Description
  Карта базового цвета.
- Name
  metallic
  Type
  string
  Description
  Карта металличности. Отсутствует, если вы создали задачу с enable_pbr: false.
- Name
  normal
  Type
  string
  Description
  Карта нормалей. Отсутствует, если вы создали задачу с enable_pbr: false.
- Name
  roughness
  Type
  string
  Description
  Карта шероховатости. Отсутствует, если вы создали задачу с enable_pbr: false.
- Name
  emission
  Type
  string
  Description
  Карта свечения. Отсутствует в любом из следующих случаев:
  
  Вы создали задачу с enable_pbr: false.
  
  ai_model равно meshy-6-lite, meshy-7, meshy-7.1 или latest.
  
  texture_resolution равно 8k.
  
  Задача уточняет (refine) превью meshy-t2 или meshy-t2.5 без указания ai_model.
Name
preceding_tasks
Type
integer
Description
Количество задач перед этой в очереди. Значение имеет смысл только пока задача находится в статусе PENDING.
Name
task_error
Type
object
Description
Подробности ошибки при неудачном выполнении задачи. Значение null, если статус не FAILED. См. Ошибки.
Name
consumed_credits
Type
integer
Description
Количество кредитов, использованных задачей. Присутствует, когда статус PENDING, IN_PROGRESS или SUCCEEDED. Значение 0 для задачи со статусом FAILED, так как Meshy возвращает кредиты при неудачном выполнении задачи.