promptstringОбязательноДля объекта по тексту: Обязательное описание до 1024 символов: целый предмет, форма, материал, цвет, стиль и размер.
- По умолчанию
- Не задано
- Ограничения
- minLength:1maxLength:1024
tripo/h3.1/text-to-3dTripo H3.1 Text to 3D превращает описание предмета в 3D-объект, обычно GLB с текстурами. Сначала создаётся опорное изображение, затем сетка. `image_seed` относится к первому этапу; для геометрии и текстур предусмотрены отдельные значения seed.
Примеры используют публичные параметры выбранного эндпоинта. Замените API-ключ и примеры медиафайлов, затем отправьте запрос со своего сервера.
SDK и интеграцииhttps://api.spicyapi.ai/api/v1/jobs/createTaskХраните API-ключ в серверной переменной окружения SPICY_API_KEY. Используйте Bearer-аутентификацию и Content-Type: application/json для JSON-запросов.
Authorization: Bearer $SPICY_API_KEY# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "tripo/h3.1/text-to-3d",
"input": {
"prompt": "A ceramic teapot on a linen cloth, soft window light, muted palette",
"low_poly": false,
"quad_mesh": false,
"generate_pbr": true,
"generate_parts": false,
"texture_quality": "standard"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"Пример построен по входной схеме этой модели — той же, по которой API проверяет каждый запрос.
Поместите эти поля в объект input тела запроса. Имена и типы соответствуют API. Не предполагайте значение по умолчанию, если оно не задано.
promptstringОбязательноДля объекта по тексту: Обязательное описание до 1024 символов: целый предмет, форма, материал, цвет, стиль и размер.
texture_seedintegerНеобязательноДля объекта по тексту: Значение seed текстур для сравнения поверхностей без гарантии одинаковой выдачи.
image_seedintegerНеобязательноДля объекта по тексту: Значение seed опорного изображения до построения 3D для сравнений без гарантии точного повторения.
seedintegerНеобязательноДля объекта по тексту: Значение seed геометрии для сравнения одного изменения за раз, без гарантии точного повтора.
uv_unwrapbooleanНеобязательноДля объекта по тексту: Включено по умолчанию; отключение экспорта UV сокращает обработку и размер, но убирает координаты для последующих текстур.
auto_sizebooleanНеобязательноДля объекта по тексту: Выключено по умолчанию; оценивает реальные размеры и требует текстурированного результата.
face_limitintegerНеобязательноДля объекта по тексту: Цель 1000–2 000 000 граней для описанного предмета; с low_poly рекомендуется до 20 000.
generate_partsbooleanНеобязательноВлияет на ценуДля объекта по тексту: Разделяет на треугольные части без текстур; параметры и доплаты текстур и четырёхугольников заменяются доплатой за части.
low_polybooleanНеобязательноВлияет на ценуДля объекта по тексту: Низкополигональная обработка с видом ручного моделирования и своей доплатой; рекомендуется face_limit не выше 20 000.
quad_meshbooleanНеобязательноВлияет на ценуДля объекта по тексту: Создаёт четырёхугольную сетку FBX вместо GLB; при generate_parts игнорируется и не оплачивается.
geometry_qualitystringНеобязательноВлияет на ценуДля объекта по тексту: standard либо detailed; detailed добавляет детализацию геометрии и отдельную доплату.
"standard""detailed"remove_lightingbooleanНеобязательноДля объекта по тексту: Включено по умолчанию, действует только с v3.5; удаляет освещение, запечённое в изображении.
texture_versionstringНеобязательноДля объекта по тексту: Выберите стандартную v3.0-20250812 или v3.5-20260815; fast и удаление освещения используют v3.5.
"v3.0-20250812""v3.5-20260815"texture_qualitystringНеобязательноВлияет на ценуДля объекта по тексту: standard по умолчанию; detailed и extreme (8K) имеют отдельные доплаты; fast использует v3.5 по цене standard; без текстур доплаты за качество нет.
"standard""detailed""extreme""fast"generate_pbrbooleanНеобязательноВлияет на ценуДля объекта по тексту: Включено по умолчанию; материалы PBR активируют текстуры даже при выключенном generate_texture.
generate_texturebooleanНеобязательноВлияет на ценуДля объекта по тексту: Включено по умолчанию; для удаления цветовой текстуры отключите также generate_pbr.
negative_promptstringНеобязательноДля объекта по тексту: Короткие исключения до 255 символов, например основание или постамент.
{
"type": "object",
"required": [
"prompt"
],
"x-pricing": {
"billingMode": "formula",
"variantFields": []
},
"properties": {
"seed": {
"type": "integer",
"x-ui": {
"order": 20,
"widget": "number",
"advanced": true
},
"maximum": 2147483647,
"minimum": 0,
"description": "Seed for the geometry step, for reproducible shapes."
},
"prompt": {
"type": "string",
"x-ui": {
"order": 100,
"widget": "textarea",
"primary": true
},
"maxLength": 1024,
"minLength": 1,
"description": "Describe the object to build: shape, material, colour, style and scale. One object, fully visible. Up to 1,024 characters."
},
"low_poly": {
"type": "boolean",
"x-ui": {
"order": 68,
"widget": "switch",
"affects_price": true
},
"default": false,
"description": "Build a low-poly mesh with clean, hand-modelled-style topology instead of a dense scan-like one. Best for simple objects; keep face_limit at 20,000 or below with it. Off by default; adds to the price."
},
"auto_size": {
"type": "boolean",
"x-ui": {
"order": 30,
"widget": "switch",
"advanced": true,
"affects_price": false
},
"default": false,
"description": "Scale the mesh to estimated real-world dimensions. Off by default."
},
"quad_mesh": {
"type": "boolean",
"x-ui": {
"order": 70,
"widget": "switch",
"affects_price": true
},
"default": false,
"description": "Return four-sided (quad) polygons instead of triangles, for editing in modelling tools; the file then comes back as FBX instead of GLB. Off by default; adds to the price. Ignored when generate_parts is on."
},
"uv_unwrap": {
"type": "boolean",
"x-ui": {
"order": 25,
"widget": "switch",
"advanced": true,
"affects_price": false
},
"default": true,
"description": "Unwrap UV coordinates during generation. On by default; turning it off is faster and gives a smaller file, but the mesh then has no UVs for texturing later. Does not change the price."
},
"face_limit": {
"type": "integer",
"x-ui": {
"step": 1000,
"order": 65,
"widget": "slider",
"affects_price": false
},
"maximum": 2000000,
"minimum": 1000,
"description": "Target face count, 1,000 to 2,000,000. Leave empty to let the model decide (often over a million faces). Does not change the price."
},
"image_seed": {
"type": "integer",
"x-ui": {
"order": 15,
"widget": "number",
"advanced": true
},
"maximum": 2147483647,
"minimum": 0,
"description": "Seed for the first step, which draws a reference picture from the prompt. Keep it fixed to keep the same starting picture."
},
"generate_pbr": {
"type": "boolean",
"x-ui": {
"order": 85,
"widget": "switch",
"affects_price": true
},
"default": true,
"description": "Add PBR material maps (metal-roughness and normal). On by default and switches texturing on."
},
"texture_seed": {
"type": "integer",
"x-ui": {
"order": 10,
"widget": "number",
"advanced": true
},
"maximum": 2147483647,
"minimum": 0,
"description": "Seed for the texture step. Keep seed fixed and change this to try new textures on the same shape."
},
"generate_parts": {
"type": "boolean",
"x-ui": {
"order": 67,
"widget": "switch",
"affects_price": true
},
"default": false,
"description": "Return the model split into separate, editable parts. Parts are untextured triangle meshes, so the texture options and quad_mesh are ignored and not charged. Off by default; costs more than the textured default."
},
"negative_prompt": {
"type": "string",
"x-ui": {
"order": 96,
"widget": "textarea",
"advanced": true
},
"maxLength": 255,
"description": "What the object should not have, written as a short list. Up to 255 characters."
},
"remove_lighting": {
"type": "boolean",
"x-ui": {
"order": 77,
"widget": "switch",
"affects_price": false
},
"default": true,
"description": "Remove the lighting and shadows baked into the picture before texturing, so the texture reacts cleanly to scene lights. On by default; only takes effect with the v3.5 texture model. Does not change the price."
},
"texture_quality": {
"enum": [
"standard",
"detailed",
"extreme",
"fast"
],
"type": "string",
"x-ui": {
"order": 80,
"widget": "radio",
"enum_labels": {
"fast": "Fast",
"extreme": "8K",
"detailed": "Detailed",
"standard": "Standard"
},
"affects_price": true
},
"default": "standard",
"description": "Texture quality: standard (the default), detailed (higher resolution), extreme (8K) or fast (standard size, generated quicker with the v3.5 texture model). detailed and extreme cost more and only apply to textured meshes."
},
"texture_version": {
"enum": [
"v3.0-20250812",
"v3.5-20260815"
],
"type": "string",
"x-ui": {
"order": 78,
"widget": "radio",
"enum_labels": {
"v3.0-20250812": "v3.0",
"v3.5-20260815": "v3.5"
},
"affects_price": false
},
"default": "v3.0-20250812",
"description": "Texture model version: v3.0-20250812 (the default) or the newer v3.5-20260815. texture_quality fast and remove_lighting use v3.5. Does not change the price."
},
"generate_texture": {
"type": "boolean",
"x-ui": {
"order": 90,
"widget": "switch",
"affects_price": true
},
"default": true,
"description": "Paint a texture onto the mesh. On by default; turning it off only removes texturing if generate_pbr is off too."
},
"geometry_quality": {
"enum": [
"standard",
"detailed"
],
"type": "string",
"x-ui": {
"order": 75,
"widget": "radio",
"enum_labels": {
"detailed": "Detailed",
"standard": "Standard"
},
"affects_price": true
},
"default": "standard",
"description": "Geometry detail: standard (the default) or detailed. detailed builds finer surface detail and costs more."
}
},
"additionalProperties": false
}HTTP 202 означает принятие задачи, а не завершение генерации. Сохраните полученный taskId и проверяйте эту задачу. Не создавайте новую, пока ждёте результат.
HTTP/1.1 202 Accepted
Location: /api/v1/jobs/recordInfo?taskId=job_01k3m8x9q2z4v7n5p6r8s0t1w3
{
"code": 200,
"msg": "success",
"request_id": "req_example_create",
"data": {
"taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
"state": "queued",
"estimatedCost": "0.750000"
}
}В ответе о приёме есть оценка стоимости — приложение сможет показать ту же сумму в истории задач и в расчётах.
curl --get "https://api.spicyapi.ai/api/v1/jobs/recordInfo" \
--data-urlencode "taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"Начните с интервала около 2 секунд и постепенно увеличивайте его. Прекратите опрос при конечном состоянии. После сбоя соединения используйте исходный taskId. Повторно создавать задачу можно только с исходным ключом идемпотентности и исходным телом запроса.
import { verifyWebhook } from "@spicyapi/sdk";
// express.raw keeps the bytes we signed; express.json never matches.
app.post("/hooks/spicy", express.raw({ type: "application/json" }), (req, res) => {
const { payload } = verifyWebhook({
rawBody: req.body,
timestamp: req.header("X-Webhook-Timestamp"),
signature: req.header("X-Webhook-Signature"),
payloadVersion: Number(req.header("X-Webhook-Payload-Version")),
secret: process.env.SPICY_WEBHOOK_SECRET,
});
res.status(200).end();
void handleFinishedTask(payload);
});Передайте callBackUrl при создании задачи — готовая запись придёт к вам POST-запросом, и никакого опроса не понадобится. В каждой доставке есть X-Webhook-Timestamp, X-Webhook-Signature и X-Webhook-Payload-Version. Подпись — это HMAC-SHA256 в base64 от taskId.timestamp.sha256(body), поэтому проверять её нужно по исходным байтам: если разобрать JSON и сериализовать заново, байты изменятся и проверка не пройдёт. Неудачные доставки повторяются, так что один и тот же taskId может прийти дважды — сделайте обработчик идемпотентным. Сначала ответьте 2xx, работу выполняйте после: медленный обработчик считается неудачной доставкой.
Обрабатывайте output только при state, равном succeeded. При ошибке проверьте errorCode, errorMessage и request_id. Стоимость и состояния в примерах не являются фактическим счётом.
{
"code": 200,
"msg": "success",
"request_id": "req_example_record",
"data": {
"taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
"model": "tripo/h3.1/text-to-3d",
"state": "succeeded",
"output": {
"assets": [
{
"key": "tasks/2026/08/28/job_01k3m8x9q2z4v7n5p6r8s0t1w3/3f7a1c9e5b2d48f0a6c1e3d5b7f9a1c3.png",
"mime": "image/png",
"url": "https://example.r2.cloudflarestorage.com/results/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.png?X-Amz-Signature=SIGNATURE_FROM_RESPONSE",
"expiresAt": "2026-08-28T12:20:08.000Z"
}
]
},
"cost": "0.750000",
"settled": true,
"createdAt": "2026-08-28T12:00:00Z",
"completedAt": "2026-08-28T12:00:30Z"
}
}Доступные файлы можно открыть или скачать по assets[].url без заголовка API Authorization. Подписанная ссылка действует до expiresAt. Чтобы обновить её, повторно запросите задачу в течение срока хранения файла. У ожидающих или недоступных файлов URL отсутствует. Не передавайте подписанные ссылки посторонним.
Используйте SpicyAPI в приложении, терминале, ИИ-ассистенте или визуальном процессе. Выберите руководство по настройке.
Писать код выше вовсе не обязательно. Подключите сервер MCP один раз — и любой агент, который говорит на MCP (Claude Code, Codex, Cursor, Windsurf, VS Code, Gemini CLI, Cline, LibreChat), вызовет эту модель по имени. Либо запустите её из терминала одной командой.
Возьми tripo/h3.1/text-to-3d и сгенерируй портрет танцовщицы в неоновом свете, сохрани в ./out/.
Агент найдёт модель в каталоге, сам загрузит локальный файл, покажет точную смету и предельную сумму списания — и дождётся вашего согласия. До этого ничего не списывается.
claude mcp add spicyapi -e SPICY_API_KEY=$SPICY_API_KEY \
-- npx --yes --package=@spicyapi/mcp spicyapi-mcp
npx skills add spicyapi-ai/spicy-skillПервая строка даёт агенту инструменты, вторая — Skill, то есть правила обращения с ними: сначала смета, потом списание; локальные файлы загружать, а не вставлять байтами; URL готового результата читать, а не угадывать. Остальные клиенты подключают тот же сервер через собственный файл настроек — см. раздел для разработчиков.
npx @spicyapi/cli tasks create --model tripo/h3.1/text-to-3d \
--input-json '{"prompt":"A ceramic teapot on a linen cloth, soft window light, muted palette","low_poly":false,"quad_mesh":false,"generate_pbr":true,"generate_parts":false,"texture_quality":"standard"}' \
--waitВходные данные взяты из схемы этого эндпоинта — той же, что и в примерах выше. --wait дождётся завершения задачи и выведет её, а --yes пропустит подтверждение в CI. Сначала задайте SPICY_API_KEY: один ключ работает и для API, и для CLI, и для сервера MCP.
npx @spicyapi/cli tasks create --model tripo/h3.1/text-to-3d \
--input-json '{…}' --retention 1h --wait
npx @spicyapi/cli tasks get $TASK_ID # read back the retention that appliedКлюч --retention только сокращает срок — 30m, 1h, 7d или 0, чтобы удалить сразу после перехода задачи в конечное состояние. Реально действует наименьшее из трёх: ваш запрос, настройки аккаунта и предел платформы, — поэтому считайте его из записи задачи, а не исходите из того, что запрошенное число применилось. Запросить срок больше разрешённого аккаунтом нельзя: это ничего не изменит.
Установите узлы SpicyAPI через ComfyUI Manager или командой ниже и найдите на холсте Tripo H3.1 · Text to 3D. У узла те же параметры, что и на этой странице, а цена показывается до запуска.
cd ComfyUI/custom_nodes
git clone https://github.com/spicyapi-ai/comfyui-spicyapiВстроенная панель читает ту же схему, что и эта страница, поэтому не может разойтись с API. Если содержимое должно индексироваться поиском по документации, возьмите JSON из /api/embed/models/ и отрисуйте его самостоятельно.
<iframe src="https://spicyapi.ai/embed/ru/models/tripo-h3-1/api?model=tripo%2Fh3.1%2Ftext-to-3d" width="100%" height="560" loading="lazy" title="Пример запроса" style="border:1px solid rgba(0,0,0,.12)"></iframe>