Text to 3D API

Text to 3D API — это функция, которая позволяет интегрировать возможности Текст в 3D от Meshy в ваше собственное приложение. В этом разделе вы найдёте всю информацию, необходимую для начала работы с этим API.

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

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

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

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

Параметры

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

    Это поле должно быть установлено в "preview" при создании задачи предпросмотра.

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

    Опишите, какой объект представляет собой 3D модель. Максимум 800 символов.

  • Name
    model_type
    Type
    string
    по умолчанию standard
    Description

    Укажите тип генерации 3D сетки.

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

    • standard: Обычная генерация 3D сетки с высокой детализацией.
    • smart-topology: Выберите модель Smart Topology с ai_model (meshy-t2).
    • lowpoly (устаревшее): Генерирует низкополигональную сетку, оптимизированную для более чистых полигонов. Рекомендуем использовать smart-topology вместо этого.

    Когда выбран smart-topology, should_remesh и decimation_mode игнорируются, и принимается только topology: triangle.

    Когда выбран lowpoly, ai_model, topology, target_polycount и should_remesh игнорируются.

  • Name
    ai_model
    Type
    string
    по умолчанию latest
    Description

    ID используемой модели. Доступные значения зависят от 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 (по умолчанию): модель Smart Topology — более чистая topology, естественно разделённые части, вывод в виде треугольников и количество граней, которое можно задать через target_polycount.
  • Name
    geometry_resolution
    Type
    string
    по умолчанию standard
    Description

    Проход генерации геометрии. 2k запускает Ultra-проход при 2048³; 4k запускает его при 4096³ для наиболее тонкой детализации поверхности.

    Доступные значения: standard, 2k, 4k

    Поддерживается только в mode preview. Требует meshy-7.1 или latest.

  • Name
    ultra_mode
    Type
    boolean
    ⚠ устаревший
    по умолчанию false
    Description

    Используйте geometry_resolution вместо этого. ultra_mode: true эквивалентно geometry_resolution: "2k".

  • Name
    should_remesh
    Type
    boolean
    по умолчанию false (Meshy 6 and Meshy 7 models), true (others)
    Description

    Управляет включением фазы ремешинга. Для модели с наивысшим качеством мы рекомендуем устанавливать should_remesh в false.

Применяется только когда should_remesh = true
  • Name
    topology
    Type
    string
    по умолчанию triangle
    Description

    Укажите topology генерируемой модели.

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

    • quad: Генерирует сетку с преобладанием четырёхугольников.
    • triangle: Генерирует децимированную треугольную сетку.

    Вывод Smart Topology состоит только из треугольников. Запрос quad вместе с ai_model: meshy-t2 возвращает ошибку.

  • Name
    decimation_mode
    Type
    integer
    Description

    Включите адаптивную децимацию, задав уровень числа полигонов. При установке target_polycount игнорируется.

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

    • 1: Адаптивный — сверхвысокое число полигонов.
    • 2: Адаптивный — высокое число полигонов.
    • 3: Адаптивный — среднее число полигонов.
    • 4: Адаптивный — низкое число полигонов.
  • Name
    target_polycount
    Type
    integer
    Description

    Целевое число полигонов (граней) в результате. Фактическое число может отличаться от целевого в зависимости от геометрии.

    target_polycount действует в двух независимых случаях:

    • Ремешинг — с should_remesh: true для модели standard. Сетка ремешируется (децимируется) до приблизительно этого числа. Диапазон от 100 до 300 000, по умолчанию 30 000. Если задан decimation_mode, он имеет приоритет, и target_polycount игнорируется.
    • Smart Topology — с model_type: smart-topology и ai_model: meshy-t2. Модель генерируется напрямую с этим числом граней; ремешинг не запускается, и should_remesh не требуется. Диапазон от 100 до 15 000, по умолчанию 4 000.
  • Name
    symmetry_mode
    Type
    string
    ⚠ устаревший
    по умолчанию auto
    Description

    Устарело. Этот параметр больше не влияет на результат.

    Поле symmetry_mode управляет поведением симметрии во время процесса генерации модели.

    Допустимые значения:

    • 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-6. Запросы с использованием Meshy-6 будут игнорировать art_style, а некоторые комбинации могут вызывать ошибки. Доступные значения: realistic, sculpture.

    enable_pbr должен быть установлен в false при использовании стиля Sculpture, так как стиль Sculpture генерирует собственный набор PBR-карт.

  • Name
    moderation
    Type
    boolean
    по умолчанию false
    Description

    Если установлено в true, входной контент будет автоматически проверяться на потенциально вредоносный контент. Если вредоносный контент обнаружен, задача не перейдёт к генерации.

    Проверяться будет текст из prompt.

  • Name
    target_formats
    Type
    string[]
    Description

    Указывает, какие 3D файловые форматы включать в результат. Будут сгенерированы и возвращены только запрошенные форматы, что может уменьшить время выполнения задачи. Если параметр не указан, включаются все поддерживаемые форматы.

    Доступные значения: glb, obj, fbx, stl, usdz, 3mf

    Если параметр не указан, генерируются все форматы, кроме 3mf. 3mf включается только при явном указании.

  • Name
    alpha_thumbnail
    Type
    boolean
    по умолчанию false
    Description

    Если установлено в true, задача дополнительно рендерит версию предпросмотра с прозрачным фоном (RGBA) и возвращает её как alpha_thumbnail_url в ответе GET. Существующее поле thumbnail_url остаётся неизменным.

  • Name
    auto_size
    Type
    boolean
    по умолчанию false
    Description

    Если установлено в true, сервис использует AI-зрение для автоматической оценки реальной высоты объекта и соответствующего изменения размера модели. Начало координат по умолчанию будет bottom, если не задано явно через origin_at.

Применяется только когда auto_size = true
  • Name
    origin_at
    Type
    string
    по умолчанию bottom
    Description

    Положение начала координат, когда включён auto_size.

    Доступные значения: bottom, center.

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

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

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

  • Name
    400 - Bad Request
    Description

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

    • Отсутствующий параметр: Отсутствует обязательный параметр (например, prompt, mode).
    • Недопустимый параметр: art_style не является одним из допустимых значений.
    • Слишком длинный prompt: prompt превышает лимит символов.
    • Неподдерживаемая модель для low poly: ai_model: "meshy-6-lite" не поддерживает model_type: "lowpoly".
    • Неподдерживаемая модель для Ultra: geometry_resolution требует meshy-7.1 или latest.
  • Name
    401 - Unauthorized
    Description

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

  • Name
    402 - Payment Required
    Description

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

  • Name
    429 - Too Many Requests
    Description

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

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"
}
POST/openapi/v2/text-to-3d

Создать задачу Refine для Text to 3D

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

Параметры

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

    Это поле должно быть установлено в значение "refine" при создании задачи refine.

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

    Идентификатор соответствующей preview-задачи.

    Статус указанной preview-задачи должен быть SUCCEEDED.

  • Name
    enable_pbr
    Type
    boolean
    по умолчанию false
    Description

    Генерировать PBR-карты (metallic, roughness, normal) в дополнение к базовому цвету. Карта эмиссии также включается, когда ai_model имеет значение meshy-6, за исключением случая texture_resolution: 8k (карта эмиссии не создаётся). meshy-6-lite, meshy-7.1 и latest не создают карту эмиссии.

  • Name
    texture_resolution
    Type
    string
    по умолчанию 2k
    Description

    Разрешение текстуры базового цвета. Одно из значений: 2k (2048×2048), 4k (4096×4096) или 8k (8192×8192). Более высокое разрешение позволяет захватить больше деталей поверхности. Применяется только в mode refine.

    4k и 8k требуют ai_model meshy-6, meshy-7.1 или latest. При 8k карта эмиссии не создаётся.

  • Name
    hd_texture
    Type
    boolean
    ⚠ устаревший
    по умолчанию false
    Description

    Используйте вместо этого texture_resolution — эквивалентно texture_resolution: "4k". Если заданы оба параметра, приоритет имеет texture_resolution.

  • Name
    texture_prompt
    Type
    string
    Description

    Предоставьте дополнительный текстовый prompt для управления процессом текстурирования. Максимум 800 символов.

  • Name
    texture_image_url
    Type
    string
    Description

    Предоставьте 2D-изображение для управления процессом текстурирования. В настоящее время поддерживаются форматы .jpg, .jpeg и .png.

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

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

    Текстурирование по изображению может работать не оптимально при значительных различиях в геометрии между исходным asset и загруженным изображением. Для управления процессом текстурирования можно использовать только один из параметров: texture_image_url или texture_prompt. Если указаны оба параметра, то по умолчанию для текстурирования модели будет использоваться texture_prompt.

  • Name
    ai_model
    Type
    string
    по умолчанию inherited from the preview task
    Description

    ID модели, используемой для refine.

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

    • meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
    • meshy-7 (устаревшее): используйте вместо этого meshy-7.1.

    Опустите этот параметр, чтобы наследовать модель, использованную preview-задачей — это гарантирует, что preview и её refine используют одну и ту же модель на всех этапах. Передайте явное значение, чтобы переопределить это наследование.

    Явное значение latest разрешается здесь точно так же, как и в preview-задаче (в настоящее время это Meshy 7.1), поэтому preview с latest и её refine с latest всегда используют одну и ту же модель текстурирования.

  • Name
    moderation
    Type
    boolean
    по умолчанию false
    Description

    Если установлено значение true, входной контент будет автоматически проверен на наличие потенциально вредоносного содержимого. Если обнаружен вредоносный контент, задача не перейдёт к этапу генерации.

    Проверке подвергаются как текст из texture_prompt, так и изображение из texture_image_url.

  • Name
    remove_lighting
    Type
    boolean
    по умолчанию true
    Description

    Удаляет светлые участки и тени с текстуры базового цвета, обеспечивая более чистый результат, который лучше работает с пользовательскими настройками освещения.

    Действует только когда ai_model имеет значение meshy-6; другие модели игнорируют этот параметр.

  • Name
    target_formats
    Type
    string[]
    Description

    Указывает, какие форматы 3D-файлов включить в результат. Будут сгенерированы и возвращены только запрошенные форматы, что может сократить время выполнения задачи. Если параметр не указан, включаются все поддерживаемые форматы.

    Доступные значения: glb, obj, fbx, stl, usdz, 3mf

    Если параметр не указан, генерируются все форматы, кроме 3mf. 3mf включается только при явном указании.

  • Name
    alpha_thumbnail
    Type
    boolean
    по умолчанию false
    Description

    Если установлено значение true, задача дополнительно рендерит версию превью с прозрачным фоном (RGBA) и возвращает её как alpha_thumbnail_url в ответе GET. Существующее поле thumbnail_url остаётся без изменений.

  • Name
    auto_size
    Type
    boolean
    по умолчанию false
    Description

    Если установлено значение true, сервис использует AI vision для автоматической оценки реальной высоты объекта и соответствующего изменения размера модели. Начало координат по умолчанию будет bottom, если только origin_at не задано явно.

Применяется только когда auto_size = true
  • Name
    origin_at
    Type
    string
    по умолчанию bottom
    Description

    Положение начала координат, когда включён auto_size.

    Доступные значения: bottom, center.

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

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

Виды ошибок

  • Name
    400 - Bad Request
    Description

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

    • Недействительный ID задачи: preview_task_id недействителен или не существует.
    • Задача не готова: preview-задача ещё не завершилась успешно.
    • Несовместимость моделей: AI-модель preview-задачи несовместима с запрошенной моделью refine.
  • Name
    401 - Unauthorized
    Description

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

  • Name
    402 - Payment Required
    Description

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

  • Name
    404 - Not Found
    Description

    Preview-задача, указанная в preview_task_id, не найдена.

  • Name
    429 - Too Many Requests
    Description

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

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
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
GET/openapi/v2/text-to-3d/:id

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

Этот эндпоинт позволяет получить задачу Текст в 3D по действительному id задачи. Обратитесь к разделу Объект задачи Текст в 3D, чтобы узнать, какие свойства включены в объект задачи Текст в 3D.

Этот эндпоинт работает как для задач preview, так и для задач refine.

Параметры

  • Name
    id
    Type
    path
    Description

    Уникальный идентификатор задачи Текст в 3D, которую требуется получить.

Возвращаемые данные

Ответ содержит объект задачи Текст в 3D. Подробности см. в разделе Объект задачи Текст в 3D.

Примеры

ModeПример модели
PreviewPreview model
RefineRefined model

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": {

    "message": ""

  },

  "consumed_credits": 20
}
DELETE/openapi/v2/text-to-3d/:id

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

Этот эндпоинт безвозвратно удаляет задачу Текст в 3D, включая все связанные модели и данные. Это действие необратимо.

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

  • Name
    id
    Type
    path
    Description

    ID задачи Текст в 3D, которую нужно удалить.

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

Задача, которая всё ещё находится в статусе PENDING, удаляется, а кредиты, потраченные при её создании, возвращаются.

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

Задача в конечном статусе (SUCCEEDED, FAILED или CANCELED) удаляется без возврата средств.

Возвращает

Возвращает 200 OK при успехе или 409 Conflict, если задача находится в статусе IN_PROGRESS.

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 is left 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."
}
GET/openapi/v2/text-to-3d

List Text to 3D Tasks

Этот эндпоинт позволяет получить список задач Текст в 3D.

Параметры

  • Name
    page_num
    Type
    integer
    по умолчанию 1
    Description

    Номер страницы для пагинации.

  • Name
    page_size
    Type
    integer
    по умолчанию 10
    Description

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

  • Name
    sort_by
    Type
    string
    Description

    Поле для сортировки.

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

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

Возвращает

Возвращает список объектов Объект задачи Текст в 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": {

      "message": ""

    },

    "consumed_credits": 20
  }
]
GET/openapi/v2/text-to-3d/:id/stream

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

Этот эндпоинт транслирует обновления в реальном времени для задачи Текст в 3D с помощью Server-Sent Events (SSE).

Параметры

  • Name
    id
    Type
    path
    Description

    Уникальный идентификатор задачи Текст в 3D, для которой требуется получить поток обновлений.

Возвращает

Возвращает поток объектов задачи Текст в 3D в виде Server-Sent Events.

Для задач со статусом PENDING или IN_PROGRESS поток ответа будет содержать только необходимые поля progress и status.

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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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": {

  "message": ""

},

"consumed_credits": 20
}

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

Объект задачи Text to 3D — это единица работы, которую Meshy отслеживает для генерации 3D-модели из текстового ввода. Существует два этапа Text to 3D API: preview и refine. Этап preview предназначен для генерации 3D-модели только с сеткой, а этап refine — для генерации текстурированной 3D-модели на основе результата этапа preview.

Объект имеет следующие свойства:

Свойства

  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

    Тип задачи Text to 3D. Возможные значения: text-to-3d-preview для задач этапа preview и text-to-3d-refine для задач этапа refine.

  • Name
    model_urls
    Type
    object
    Description

    Ссылка для скачивания текстурированного файла 3D-модели, сгенерированного Meshy. Свойство для формата будет отсутствовать, если этот формат не был сгенерирован, вместо возврата пустой строки.

    • 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. Присутствует только если 3mf был запрошен через target_formats.

  • Name
    prompt
    Type
    string
    Description

    Это неизменённый prompt, использованный для создания задачи.

  • Name
    negative_prompt
    Type
    string
    ⚠ устаревший
    Description

    Сохранено для обратной совместимости. Это поле не влияет функционально на сгенерированные модели.

  • Name
    art_style
    Type
    string
    ⚠ устаревший
    Description

    Неизменённый art_style, использованный для создания задачи preview. Не поддерживается Meshy-6.

  • Name
    texture_richness
    Type
    string
    ⚠ устаревший
    Description

    Сохранено для обратной совместимости. Это поле не влияет функционально на сгенерированные модели.

  • 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

    Ссылка для скачивания изображения текстуры, использованного для управления процессом текстурирования.

  • Name
    thumbnail_url
    Type
    string
    Description

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

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    Ссылка для скачивания версии thumbnail_url с прозрачным фоном (RGBA). Присутствует только если задача была создана с alpha_thumbnail: true и прозрачное превью было успешно отрендерено; в противном случае это поле отсутствует.

  • Name
    video_url
    Type
    string
    ⚠ устаревший
    Description

    Ссылка для скачивания превью-видео. Будет удалено в будущем релизе.

  • Name
    progress
    Type
    integer
    Description

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

  • Name
    started_at
    Type
    timestamp
    Description

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

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

  • Name
    created_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

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

  • Name
    status
    Type
    string
    Description

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

  • Name
    texture_urls
    Type
    array
    Description

    Массив объектов URL текстур, сгенерированных задачей. Обычно он содержит только один объект URL текстуры. Каждый объект 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, это свойство будет отсутствовать.

  • Name
    preceding_tasks
    Type
    integer
    Description

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

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

  • Name
    task_error
    Type
    object
    Description

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

  • Name
    consumed_credits
    Type
    integer
    Description

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

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": {

    "message": ""

  },

  "consumed_credits": 20
}