Это руководство по Hunyuan API основано на текущих справочных материалах по модели OdiRouter. Начните с Hunyuan 3D Standard reference. В нём описаны идентификатор модели, конечные точки очереди и жизненный цикл задачи, необходимые для отправки задания, проверки его состояния и получения результата.
Выберите модель Hunyuan 3D для задачи
OdiRouter документирует три конечные точки очереди Hunyuan 3D. Выберите модель до составления запроса, поскольку её идентификатор и ограничения на входные данные являются частью контракта.
Модель | Идентификатор модели OdiRouter | Задокументированное назначение |
|---|---|---|
Hunyuan 3D Standard |
| Преобразование текста в 3D или изображения в 3D в рамках стандартного рабочего процесса. Она принимает ровно один из параметров: |
Hunyuan 3D Pro |
| Более контролируемое создание ассетов на основе текста, изображений, эскизов или многовидовых референсов. В её документации описаны режимы Normal и Geometry. |
Hunyuan 3D Rapid |
| Быстрые предварительные просмотры и раннее исследование ассетов на основе текста или изображений. Задокументированное ограничение для текстового запроса составляет 200 UTF-8 символов. |
Перед добавлением полей модели используйте ссылку на конкретную модель для Standard, Pro или Rapid. Полезные данные, полученные для одной конечной точки, не обязательно будут действительны для другой.
Отправьте задание Hunyuan API
Модель Standard использует базовый URL модели OdiRouter: https://api.odirouter.ai/model. Этот пример на JavaScript отправляет задачу преобразования текста в 3D-изображение. Храните API-ключ в переменной окружения, а не в клиентском коде или репозитории.
const endpoint = "tencent-hunyuan-3d";
const response = await fetch(
`https://api.odirouter.ai/model/v1/queue/${endpoint}`,
{
method: "POST",
headers: {
Authorization: "Bearer " + process.env.ODIROUTER_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
prompt: "A compact wooden side table with rounded corners",
result_format: "GLB",
enable_pbr: false,
}),
},
);
if (!response.ok) throw new Error(`Task submission failed: ${response.status}`);
const task = await response.json();
console.log(task.request_id, task.status_url, task.response_url, task.cancel_url);Ответ на создание включает request_id, а также выданные сервисом URL-адреса для проверки статуса, получения результата и отмены. Сохраняйте их вместе с записью о задаче, вместо того чтобы самостоятельно формировать пути позднее.
Проверяйте статус перед чтением результата
status guide описывает IN_QUEUE, IN_PROGRESS и COMPLETED. Опрашивайте сохранённый status_url с разумным интервалом. Общая рекомендация OdiRouter — выполнять это каждые 2–5 секунд, увеличивая интервал для медленных рабочих нагрузок.
COMPLETED — это конечное состояние, но само по себе не сигнализирует об успехе. Перед чтением вывода проверяйте наличие поля error. Задача completed может сообщить о недопустимом запросе, сбое инференса, превышении времени ожидания, заблокированном содержимом или отмене. Журналирование request_id и типа ошибки даёт оператору достаточно контекста, чтобы отличить некорректный ввод от состояния сервиса, при котором возможна повторная попытка.
Получите и обработайте сгенерированный ресурс
После успешного завершения процесса вызовите возвращенный объект response_url, как описано в объекте result guide. В ответе содержится информация о задании и массив output. Перебирайте output[].content[], поскольку результат может содержать более одного файла или другого артефакта.
Документ OdiRouter содержит URL-адреса результатов поиска, которые ограничены по времени, при этом значение по умолчанию составляет семь дней. Копируйте любой ресурс, который приложение должно сохранить, в подконтрольное вам хранилище с соответствующими средствами контроля доступа. Не размещайте URL-адрес результата на общедоступной странице или в долговременно хранящемся журнале клиента.
Планируйте тестирование и проверку затрат
Начните с небольшой тестовой задачи. Подтвердите выбранный режим ввода и возвращаемый формат, затем перенесите шаблон запроса в свой воркер или приложение. Перед отправкой производственного трафика проверьте текущие OdiRouter models page и pricing page. Доступность моделей и цены могут меняться, поэтому в этом руководстве не указана фиксированная цена.
Для новой интеграции выберите соответствующую справочную модель, сохраните URL-адреса задачи и включите обработку ошибок и хранение результатов в рабочий процесс Hunyuan API.