Руководство
Как вызвать fibo-2.0/text-to-image через API HiAPI: практика с curl и Python
На этой странице
Что будет создано в этом руководстве
Это практическое руководство, которое проведёт вас от нуля до реально полученного изображения от fibo-2.0/text-to-image в HiAPI. К концу у вас будет две вещи, готовые к запуску: команда curl, формирующая корректный запрос на генерацию изображения, и небольшая функция на Python, которая делает то же самое и возвращает результат для дальнейшей обработки.
Мы пойдём в том порядке, в котором работает большинство разработчиков. Сначала убедимся, что окружение и учётные данные на месте. Затем разберём тело запроса поле за полем, чтобы вы понимали, что чем управляет. После этого отправим вызов через curl, чтобы убедиться, что эндпоинт, ключ и тело запроса согласованы. И только после этого перенесём тот же запрос в Python, где и начинается самое интересное: разбор ответа, обработка ошибок и упаковка в функцию.
Цель — не перечислить все возможные параметры, а дать вам форму запроса, которую вы полностью понимаете, чтобы вы могли адаптировать промпт, размер вывода и окружающий код под свои задачи без догадок.
Перед отправкой первого запроса
Для успешного первого вызова нужно выполнить три условия.
Аккаунт HiAPI и API-ключ
Запросы к fibo-2.0/text-to-image требуют аутентификации. Сгенерируйте API-ключ в своём аккаунте HiAPI и не допускайте его попадания в систему контроля версий. В примерах ниже ключ читается из переменной окружения, а не задаётся жёстко — делайте так с самого начала, потому что добавлять обработку ключей задним числом утомительно.
export HIAPI_API_KEY="your-api-key-here"
Инструмент, способный отправлять HTTP-запросы
Для практической части с curl на вашей машине должен быть curl. Он поставляется вместе с macOS и большинством дистрибутивов Linux; в Windows он доступен в текущих версиях и в Windows Terminal. Для части на Python вам понадобятся Python 3 и библиотека requests — самый распространённый способ отправлять HTTP-вызовы из скриптов. Если они ещё не установлены:
pip install requests
Понимание того, что вы хотите сгенерировать
Подготовьте промпт. Модели изображений хорошо реагируют на конкретные, явные описания — субъект, стиль, освещение и композицию, — поэтому одной строки идеи обычно достаточно для начала тестирования. После первого результата вы продолжите его улучшать; это нормальный цикл.
Когда эти три пункта выполнены, всё остальное сводится к телу запроса.
Разбор запроса по полям
Вызов fibo-2.0/text-to-image — это POST-запрос с телом JSON. Тело небольшое: промпт и настройки, формирующие вывод. Вместо того чтобы заучивать полный набор данных, поймите каждое поле, чтобы осознанно его менять.
Идентификатор модели
Сам путь эндпоинта указывает на модель: fibo-2.0/text-to-image. В большинстве случаев вам не нужно передавать дополнительную строку с именем модели — маршрут, который вы вызываете, определяет, какая модель запускается. Если ваша интеграция поддерживает маршрутизацию через общий эндпоинт, поместите имя модели в константу конфигурации, чтобы можно было переключать его, не меняя место вызова.
Промпт
Это основной вход: текстовое описание желаемого изображения. Относитесь к нему как к спецификации, а не как к пожеланию. Указание субъекта, визуального стиля и композиции даёт модели больше полезной информации, чем абстрактные концепции. Храните промпт в переменной или отдельном файле, чтобы можно было быстро итерировать, не переписывая код запроса.
Настройки вывода
Запросы на изображения обычно несут небольшой набор параметров вывода — чаще всего размер или соотношение сторон генерируемого изображения, а также количество, если вы хотите несколько результатов. Используйте имена полей, документированные в справочнике моделей HiAPI для fibo-2.0/text-to-image; в примере ниже используются эти канонические имена. Если параметр не документирован для этой модели, опустите его, а не угадывайте — неизвестные поля часто становятся источником ошибок валидации.
Что не должно быть в теле запроса
Не помещайте API-ключ в JSON-тело. Аутентификация относится к заголовкам. Держать учётные данные вне тела запроса означает, что тело можно безопасно логировать и сравнивать при отладке — вы оцените это, когда первый запрос завершится ошибкой.
Рабочий запрос curl
Ниже приведён полный вызов. Замените промпт на свой и выполните команду в оболочке, где установлена переменная HIAPI_API_KEY.
curl -X POST "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "тихая гавань на рассвете, над водой стелется лёгкая дымка, широкоформатная композиция, фотографический стиль",
"size": "1024x1024",
"n": 1
}'
За что отвечает каждая часть
-X POSTзадаёт HTTP-метод. Генерация изображения — это операция создания, поэтому POST, а не GET.- URL указывает на маршрут
fibo-2.0/text-to-imageна хосте API HiAPI. Если ваш аккаунт использует региональный или проектный базовый URL, замените хост и сохраните путь. Authorization: Bearer $HIAPI_API_KEYпередаёт ваш ключ из окружения. Оболочка разворачивает переменную, поэтому ключ никогда не появляется в истории команд как буквальная строка.Content-Type: application/jsonсообщает серверу, что тело запроса — JSON. Без него многие шлюзы откажут до того, как запрос дойдёт до модели.-d '...'— это тело JSON: промпт, запрошенный размер и количество изображений.
Проверка результата
Выполните команду и сначала посмотрите на сырой вывод. Успешный вызов возвращает JSON-документ с описанием сгенерированного изображения; неудачный вызов возвращает объект ошибки. Прежде чем что-либо строить на этом, убедитесь, что вы можете отличить одно от другого невооружённым глазом. Если ответ большой, обработайте его инструментом форматирования, например jq, чтобы структура стала читаемой:
curl -s -X POST "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"тихая гавань на рассвете","size":"1024x1024","n":1}' | jq .
Как только ручной вызов сработает, вы исключите учётные данные и тело запроса из подозреваемых. Все последующие проблемы будут в вашем коде.
Тот же вызов на Python
Версия на Python делает ровно то же, что и команда оболочки, но даёт вам место для проверки входных данных, повторных попыток и сохранения результатов. Держите её компактной и явной.
import os
import requests
API_URL = "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image"
def generate_image(prompt: str, size: str = "1024x1024", n: int = 1) -> dict:
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"prompt": prompt,
"size": size,
"n": n,
}
response = requests.post(
API_URL,
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=60,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = generate_image(
"тихая гавань на рассвете, над водой стелется лёгкая дымка, широкоформатная композиция, фотографический стиль"
)
print(result)
Почему написано именно так
- Ключ читается внутри функции из окружения, поэтому при его отсутствии вызов громко упадёт при запуске, а не отправит неаутентифицированный запрос.
json=payloadпозволяетrequestsсериализовать тело и правильно установить тип содержимого. Не собирайте JSON-строки вручную в Python; это приводит к ошибкам кавычек, которые обнаруживаются только во время выполнения.timeout=60делает медленные сбои явными. Генерация изображения не мгновенна, поэтому выберите тайм-аут, который вы готовы ждать, но обязательно установите его.raise_for_status()превращает ответы 4xx и 5xx в исключения. Именно эта строка не позволяет неудачному вызову молча обрабатываться как успешный.- Функция принимает
prompt,sizeиnв качестве аргументов, поэтому остальная часть вашей программы может вызывать её так же, как любую другую библиотечную функцию.
Запустите файл, и вы должны увидеть ту же структуру JSON, что и при вызове curl.
Чтение ответа и обработка ошибок
Успешный ответ даёт вам JSON-объект с описанием сгенерированного вывода. Деталь, которая вас интересует, — само сгенерированное изображение, обычно URL или ссылка, которую можно скачать или сохранить, — а также любые метаданные, которые API возвращает о запросе. Разбирайте ответ как данные; не извлекайте его строковыми операциями. Если форма при первой проверке реального ответа не соответствует ожиданиям, сначала сверьтесь со справочником моделей, а не корректируйте парсер, потому что угадывание имён полей — это типичный способ, которым интеграции незаметно ломаются.
Обнаружение сбоев
Стоит намеренно обрабатывать три уровня сбоев.
Ошибки транспорта. Запрос не завершился: сбой DNS, сброс соединения, тайм-аут. В Python они проявляются как requests.exceptions, их безопасно повторять с задержкой.
HTTP-статусы ошибок. Сервер ответил, но отклонил запрос. 401 обычно означает, что ключ отсутствует или неверен; ошибки валидации 4xx обычно означают неверное имя поля или значение; 429 означает, что вы отправляете слишком быстро; 5xx означает проблему на стороне сервера. raise_for_status() перехватывает всё это как одно исключение, поэтому перед решением, что делать, проверьте сообщение в теле ответа.
Статус 200, но неожиданное тело ответа. Вот почему нужно проверять структуру, а не предполагать. Проверяйте наличие полей, на которые вы полагаетесь, перед использованием; даже при статусе 200 считайте отсутствие ссылки на изображение сбоем.
try:
result = generate_image("тихая гавань на рассвете")
image = result.get("data", [{}])[0]
except requests.HTTPError as exc:
print("request failed:", exc.response.status_code, exc.response.text)
Важная привычка: никогда не проглатывайте ошибки молча. Как минимум логируйте код статуса и тело ответа, потому что эта пара говорит вам, нужно ли исправить тело запроса или подождать и повторить попытку.
Путь к производственной эксплуатации
Когда одиночный вызов работает, а сбои видны, несколько небольших привычек помогут интеграции выдержать реальный трафик.
Повторяйте только безопасные повторы
Ошибки транспорта, тайм-ауты, ответы 429 и 5xx стоит повторять с экспоненциальной задержкой и ограничением числа попыток. Ошибки валидации и 401 — нет; повтор неправильно сформированного запроса только расходует квоту. Явно различайте эти две категории в обработке ошибок.
Держите конфигурацию вне кода
Поместите базовый URL API, путь модели, размеры по умолчанию и тайм-ауты в конфигурацию, а не разбрасывайте по функциям. Когда вы перейдёте из тестовой среды в другую или позже попробуете похожую модель, нужно будет изменить только одно место.
Логируйте запросы и ответы, но без ключей
Логируйте промпт, параметры, коды статуса и усечённые ответы. Никогда не логируйте API-ключ. Это позволит вам через неделю ответить на вопрос «почему это изображение получилось неверным», не воспроизводя ситуацию.
Проверяйте входные данные перед отправкой
Проверьте, что промпт не пуст и имеет разумную длину, а size и n соответствуют документированным значениям модели. Локальное обнаружение неверных значений быстрее и дешевле, чем сетевой обмен.
Сохраняйте результаты, а не только выводите их
Ссылки на сгенерированные изображения могут быть временными. Скачивайте или копируйте вывод в собственное хранилище в рамках той же задачи и записывайте, какой промпт и параметры его создали. Эта запись делает возможной повторную генерацию и аудит.
Обернув fibo-2.0/text-to-image в небольшую функцию generate_image из этого руководства, позвольте остальной части приложения зависеть от этой функции, а не от сырых HTTP-вызовов. Когда вы будете готовы масштабно менять промпты, справочник моделей HiAPI — это место, где вы проверите поддерживаемые параметры перед расширением интерфейса.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий