Текст в 3D-модель

POST /v3/generation/text-to-model

Создайте 3D-модель из текстовой подсказки.

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

Заголовки запросов

Параметр	Тип	Требуется	По умолчанию	Описание
Content-Type	строка	Да	-	`application/json`
Authorization	строка	Да	-	`Bearer {api_key}`

Параметр	Тип	Требуется	По умолчанию	Описание
prompt	строка	Да	-	Текстовое приглашение, до 1024 символов.
model	строка	Нет	`tripo-v3.1`	Версия модели AI. Поддерживаемые значения: `tripo-p1`, `tripo-turbo`, `tripo-v3.1`, `tripo-v3.0`, `tripo-v2.5`, `tripo-v2.0`.
negative_prompt	строка	Нет	-	Отрицательная подсказка, до 255 символов.
model_seed	целое число	Нет	Случайный	Случайное начальное значение для генерации геометрии
image_seed	целое число	Нет	Случайный	Случайное начальное значение для этапа преобразования текста в изображение
face_limit	целое число	Нет	Адаптивный	Максимальный полисчет для вывода
texture	логическое значение	Нет	`true`	Включить текстурные карты
pbr	логическое значение	Нет	`true`	Включите материалы PBR. При включении `texture` принудительно переключается на `true`.
texture_seed	целое число	Нет	Случайный	Случайное начальное значение для генерации текстур
texture_quality	строка	Нет	`standard`	Качество текстур. Поддерживаемые значения: `fast` (требуется `texture_version=v3.5-20260815`), `standard`, `detailed`, `extreme`.
texture_version	строка	Нет	Выводится из model	Задаёт модель текстурирования независимо от геометрии. Поддерживаемые значения: `v3.5-20260815`, `v3.0-20250812`, `v2.5-20250123`. Если не указано, выводится из `model` геометрии (геометрия v2.5 → `v2.5-20250123`, иначе `v3.0-20250812`).
delight	логическое значение	Нет	`true`	Удаляет запечённое освещение из референсного изображения перед текстурированием. Учитывается только при `texture_version=v3.5-20260815`.
geometry_quality	строка	Нет	`standard`	Качество геометрии. `standard` (сбалансированный), `detailed` (ультрарежим)
auto_size	логическое значение	Нет	`false`	Автоматически масштабировать модель до реальных размеров в метрах.
quad	логическое значение	Нет	`false`	Выведите четырехугольную сетку. Если этот параметр включен, формат вывода принудительно устанавливается на FBX.
smart_low_poly	логическое значение	Нет	`false`	Создайте низкополигональную модель с созданным вручную стилем топологии.
generate_parts	логическое значение	Нет	`false`	Создавайте редактируемые сегментированные части. Несовместимо с `texture`, `pbr`, `quad` или `smart_low_poly` — см. примечание ниже
compress	строка	Нет	-	Тип сжатия. `geometry` (сжатие сети)
export_orientation	строка	Нет	`+x`	Экспортная ориентация. Доступные значения: `-x`, `-y`, `+y`.

Примечания к generate_parts:

Несовместимо с texture, pbr, quad или smart_low_poly:

texture=true или pbr=true — включая пропуск texture, который по умолчанию равен true — запрос отклоняется с кодом ошибки 1004.
quad=true — quad игнорируется; возвращаемые части представляют собой треугольные сетки.
smart_low_poly=true — smart_low_poly имеет приоритет, и части НЕ создаются.

Чтобы создать части, установите texture=false и pbr=false и не отправляйте quad или smart_low_poly.

Примечания к export_orientation:

Применяется только к этой генерации. Если модель будет использоваться в задачах постобработки (текстура, риг, ретаргет, конвертация и т. д.), рекомендуется не задавать этот параметр.
Если параметр задан, постобработка может повлиять на конечный результат из-за неправильной ориентации модели, при этом задача по-прежнему сообщает status: success — ошибка не возникает. Используйте с осторожностью.
Если вы планируете постобработку модели, оставьте этот параметр незаданным и преобразуйте ориентацию на последнем шаге через /v3/models/convert.

Следующие параметры действительны только при model >= tripo-v3.0: texture_quality, geometry_quality, auto_size, quad, smart_low_poly, generate_parts, compress.

Примеры запросов

curl -X POST https://openapi.tripo3d.ai/v3/generation/text-to-model \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "prompt": "A cat wearing a spacesuit",
    "model": "tripo-v3.1",
    "texture": true,
    "pbr": true,
    "texture_quality": "detailed"
  }'

import requests

url = "https://openapi.tripo3d.ai/v3/generation/text-to-model"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
}
payload = {
    "prompt": "A cat wearing a spacesuit",
    "model": "tripo-v3.1",
    "texture": True,
    "pbr": True,
    "texture_quality": "detailed"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

const url = "https://openapi.tripo3d.ai/v3/generation/text-to-model";

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
  },
  body: JSON.stringify({
    prompt: "A cat wearing a spacesuit",
    model: "tripo-v3.1",
    texture: true,
    pbr: true,
    texture_quality: "detailed"
  })
});

const data = await response.json();
console.log(data);

Ответ

Успешный ответ

JSON

{
  "code": 0,
  "data": {
    "task_id": "task_abc123"
  }
}

Поля ответа

Параметр	Тип	Описание
code	целое число	Код состояния. `0` указывает на успех.
data.task_id	строка	Уникальный идентификатор задачи, используемый для запроса хода создания и результатов.

Коды ошибок

HTTP Код состояния	Код ошибки	Описание	Рекомендация
429	2000	Превышен лимит генерации	Уменьшите частоту запросов и повторите попытку позже.
400	2002	Неподдерживаемый параметр запроса	Проверьте имена параметров тела запроса и диапазоны значений.
400	2008	Ввод нарушает политику в отношении контента	Пересмотрите запрос и удалите описания, нарушающие правила.
403	2010	Недостаточно кредитов	Добавьте кредиты и повторите попытку.
400	2015	Версия модели устарела	Обновите `model` до поддерживаемой на данный момент версии.
400	2018	Модель слишком сложна для повторного создания сетки.	Уменьшите `face_limit` или упростите строку ввода.