API Текст в 3D

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

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

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

Create a Text to 3D Preview Task

Этот эндпоинт создаёт задачу предпросмотра Текст в 3D, которая генерирует 3D-сетку без текстур (только геометрию) на основе текстового prompt. Это первый шаг в двухэтапном процессе. После успешного завершения предпросмотра используйте возвращённый ID задачи для создания задачи уточнения для текстурирования. См. Объект задачи Текст в 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-5, meshy-6, meshy-7, latest (Meshy 7)

    Генерация Smart Topology (model_type: smart-topology):

    • meshy-t2 (по умолчанию): модель Smart Topology — более чистая topology, изначально разделённые части, вывод в виде треугольников и число граней, которое можно задать с помощью target_polycount.
  • Name
    ultra_mode
    Type
    boolean
    по умолчанию false
    Description

    Включает генерацию Ultra для более точной геометрии с более детализированной поверхностью. Генерация занимает больше времени и добавляет 5 кредитов.

    Поддерживается только когда ai_model — meshy-7 (или latest), и только в режиме preview.

  • Name
    should_remesh
    Type
    boolean
    по умолчанию false (meshy-6, meshy-7), 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 задачи только что созданной задачи Текст в 3D.

Режимы сбоя

  • Name
    400 - Bad Request
    Description

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

    • Отсутствует параметр: Не указан обязательный параметр (например, prompt, mode).
    • Недопустимый параметр: art_style не является одним из допустимых значений.
    • Prompt слишком длинный: prompt превышает лимит символов.
  • 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 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",
  "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

Создание задачи Text to 3D Refine

Этот эндпоинт создаёт задачу Text to 3D refine, которая применяет текстуру к завершённой сетке предпросмотра (preview). Необходимо указать preview_task_id из успешной задачи предпросмотра. Это второй этап двухэтапного рабочего процесса.

Параметры

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

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

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

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

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

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

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

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

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

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

  • 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>

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

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

    Идентификатор модели, используемой для refine. Доступные значения: meshy-5, meshy-6, meshy-7, latest (Meshy 7).

    latest разрешается здесь точно так же, как и в задаче предпросмотра (в настоящее время Meshy 7), поэтому предпросмотр с 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. В meshy-7 (и latest) параметр принимается, но игнорируется.

  • 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, сервис использует ИИ-зрение для автоматической оценки реальной высоты объекта и соответствующего изменения размера модели. Начало координат по умолчанию будет 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

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

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

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

  • Name
    402 - Payment Required
    Description

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

  • Name
    404 - Not Found
    Description

    Задача предпросмотра, указанная в 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.

Этот эндпоинт работает как для предварительного просмотра, так и для уточнения задач.

Параметры

  • Name
    id
    Type
    path
    Description

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

Возвращает

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

Примеры

РежимПример модели
ПредпросмотрМодель предпросмотра
УточнениеУточненная модель

Запрос

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

Ответ

{
  "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 для удаления.

Возвращает

Возвращает 200 OK в случае успеха.

Запрос

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

Ответ

// Returns 200 Ok on success.
GET/openapi/v2/text-to-3d

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

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

Параметры

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

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

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

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

  • Name
    sort_by
    Type
    string
    Description

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

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

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

Возвращает

Возвращает список с пагинацией Объектов задач Текст в 3D.

Запрос

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

Ответ

[
  {
    "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.

Запрос

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

Поток ответа

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

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

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

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

Свойства

  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

    Тип задачи "Текст в 3D". Возможные значения: text-to-3d-preview для задач этапа предварительного просмотра и text-to-3d-refine для задач этапа уточнения.

  • Name
    model_urls
    Type
    object
    Description

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

    • Name
      glb
      Type
      string
      Description

      Скачиваемый URL-адрес файла GLB.

    • Name
      fbx
      Type
      string
      Description

      Скачиваемый URL-адрес файла FBX.

    • Name
      usdz
      Type
      string
      Description

      Скачиваемый URL-адрес файла USDZ.

    • Name
      obj
      Type
      string
      Description

      Скачиваемый URL-адрес файла OBJ.

    • Name
      mtl
      Type
      string
      Description

      Скачиваемый URL-адрес файла MTL.

    • Name
      stl
      Type
      string
      Description

      Скачиваемый URL-адрес файла STL.

    • Name
      3mf
      Type
      string
      Description

      Скачиваемый URL-адрес файла 3MF. Присутствует только, если 3mf был запрошен через target_formats.

  • Name
    prompt
    Type
    string
    Description

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

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

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

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

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

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

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

  • Name
    texture_prompt
    Type
    string
    Description

    Дополнительный текстовый prompt, предоставленный для направления процесса текстурирования на этапе уточнения.

  • Name
    ultra_mode
    Type
    boolean
    Description

    Отражает значение ultra_mode, с которым была создана задача предварительного просмотра. Присутствует только для задач предварительного просмотра meshy-7 (или latest), которые явно установили ultra_mode; в противном случае опущено.

  • Name
    texture_image_url
    Type
    string
    Description

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

  • Name
    thumbnail_url
    Type
    string
    Description

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

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

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

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

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

  • Name
    progress
    Type
    integer
    Description

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

  • Name
    started_at
    Type
    timestamp
    Description

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

    Временная метка представляет количество миллисекунд, прошедших с 1 января 1970 года по UTC, в соответствии со стандартом RFC 3339. Например, пятница, 1 сентября 2023 года, 12:00:00 по Гринвичу представляется как 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

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

    • Name
      metallic
      Type
      string
      Description

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

      Если задача создана с enable_pbr: false, это свойство будет опущено.

    • Name
      normal
      Type
      string
      Description

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

      Если задача создана с enable_pbr: false, это свойство будет опущено.

    • Name
      roughness
      Type
      string
      Description

      Скачиваемый URL-адрес изображения карты шероховатости.

      Если задача создана с enable_pbr: false, это свойство будет опущено.

    • Name
      emission
      Type
      string
      Description

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

      Если задача создана с enable_pbr: false, или ai_model — meshy-5, это свойство будет опущено.

  • 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 (кредиты возвращаются при неудаче).

Пример объекта задачи "Текст в 3D"

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