HiAPI
Блог

Руководство

Как вызвать fibo-2.0/text-to-image через API HiAPI: практика с curl и Python

Nov 13, 2026
Обложка: полупрозрачные стеклянные плоскости, наложенные на светло-серо-голубой фон, преломляют сдержанные синие цветовые полосы, образуя абстрактную геометрическую композицию.
На этой странице

Что будет создано в этом руководстве

Это практическое руководство, которое проведёт вас от нуля до реально полученного изображения от 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 — это место, где вы проверите поддерживаемые параметры перед расширением интерфейса.

Похожие статьи

Все статьи →

Начните работать с постоянными артефактами ИИ

Получите API-ключ и вызывайте модели изображений, видео и аудио через один API на основе tasks.

Читать документацию API