Руководство
Как использовать qwen-image-2.0-pro через HiAPI API: curl, Python и один рабочий запрос
Практическое интеграционное упражнение для разработчиков: первый успешный вызов, разбор структуры запроса и устранение неполадок
На этой странице
Что qwen-image-2.0-pro предоставляет пользователям API
qwen-image-2.0-pro — это модель генерации изображений, вызываемая через HTTP. С точки зрения вашего кода она ведёт себя как эндпоинт чат-дополнений: вы отправляете JSON-полезную нагрузку с описанием нужного изображения, а получаете JSON-ответ, содержащий сгенерированное изображение.
Преимущество доступа через HiAPI API — в единообразии. Один API-ключ, один базовый URL, одна структура запроса работают для разных моделей. Если позже вы смените идентификатор модели или измените параметры, окружающий код останется прежним. Вам не нужно изучать новый SDK или управлять несколькими учётными данными для каждого пробуемого image-модели.
В этом руководстве мы сначала выполним полный первый вызов через curl, затем перенесём его на Python, покажем, как извлечь изображение из ответа, и в конце приведём чек-лист для диагностики и небольшую переиспользуемую обёртку. Все примеры используют одинаковую полезную нагрузку и одну и ту же переменную окружения для ключа, поэтому то, что работает в терминале, без изменений запустится и в скрипте.
Предварительные условия и подготовка ключа
Прежде чем писать код, убедитесь, что готовы три вещи.
1. Учётная запись HiAPI и API-ключ
Создайте учётную запись и сгенерируйте API-ключ в панели управления. Ключ конфиденциален — обращайтесь с ним как с паролем. Не вставляйте его в исходные файлы, которые попадут в систему контроля версий.
2. Экспорт ключа в переменную окружения
Приведённые ниже примеры читают ключ из HIAPI_API_KEY, поэтому одни и те же команды и скрипты работают локально и в CI без изменений.
export HIAPI_API_KEY="your_key_here"
В Windows PowerShell используйте $env:HIAPI_API_KEY = "your_key_here". В CI задайте его как секретную переменную окружения в конфигурации конвейера.
3. Инструмент для HTTP-запросов
curl обычно уже установлен. Для Python вам понадобятся Python 3 и библиотека requests:
pip install requests
Прежде чем продолжить, убедитесь, что оболочка видит ключ:
# macOS / Linux
echo "${HIAPI_API_KEY:0:4}..."
Если вывода нет, переменная не задана, и все запросы будут завершаться ошибкой аутентификации. Сначала решите эту проблему.
Минимальный рабочий запрос через curl
Самый быстрый способ проверить связность — выполнить вызов curl, читая ключ из переменной окружения. Полезная нагрузка — это JSON-объект с полем model и массивом messages в стиле чат-дополнений.
curl -sS https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen-image-2.0-pro",
"messages": [
{
"role": "user",
"content": "A small ceramic mug on a wooden table, soft morning light, product photo"
}
]
}'
Здесь важны три детали. Заголовок Authorization использует схему Bearer. Значение model должно точно совпадать с идентификатором модели. content — это обычная строка-подсказка с описанием изображения.
При успешном запросе вы увидите в терминале распечатанный JSON-ответ. При неудаче — HTTP-код состояния и сообщение об ошибке. Проверяйте код состояния до чтения тела ответа: 401 означает неверный или отсутствующий ключ, 400 обычно указывает на некорректную полезную нагрузку, а 404 или ошибка «модель не найдена» — на неверный идентификатор модели.
Как только эта команда вернёт успешный ответ, связность подтверждена, и можно переходить к написанию кода.
Тот же запрос на Python
При переносе вызова на Python сохраняйте полезную нагрузку идентичной. Отличаются только способы чтения переменных окружения и сериализации запроса.
import json
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"model": "qwen-image-2.0-pro",
"messages": [
{
"role": "user",
"content": "A small ceramic mug on a wooden table, soft morning light, product photo",
}
],
}
response = requests.post(
"https://api.hiapi.ai/v1/chat/completions",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(json.dumps(data, indent=2))
Обратите внимание: json=payload заставляет requests автоматически установить заголовок Content-Type и сериализовать тело запроса. timeout важен, поскольку генерация изображений может занимать больше времени, чем типичные текстовые дополнения; 120 секунд — разумная отправная точка. raise_for_status() превращает ошибочные коды состояния в исключения, поэтому сбой не пройдёт незамеченным.
Запустите этот скрипт — вы должны получить тот же JSON, что и в curl. Если нет, значит, ваше окружение отличается от оболочки, где curl успешно работал; чаще всего дело в переменной ключа.
Чтение ответа и обработка вывода изображения
Ответ следует структуре чат-дополнений, поэтому сгенерированное изображение извлекается тем же путём, что и текстовый ответ. Сначала изучите распечатанный JSON; его структура будет знакомой:
{
"choices": [
{
"message": {
"role": "assistant",
"content": "..."
}
}
]
}
Сгенерированное изображение появляется в содержимом сообщения ассистента, обычно в виде URL или base64-кодированной полезной нагрузки, в зависимости от того, как модель возвращает медиа. Не предполагайте, какой именно вариант; прочитайте значение и обработайте его по префиксу:
content = data["choices"][0]["message"]["content"]
if isinstance(content, str) and content.startswith("http"):
image_url = content
# Download and save if you want a local copy
image_bytes = requests.get(image_url, timeout=60).content
with open("output.png", "wb") as f:
f.write(image_bytes)
print("saved output.png from URL")
else:
# Treat as base64-encoded image data
import base64
image_bytes = base64.b64decode(content)
with open("output.png", "wb") as f:
f.write(image_bytes)
print("saved output.png from base64")
Два практических замечания. Если содержимое — URL, считайте его временной ссылкой и скачайте как можно скорее, а не используйте его напрямую в продукте. Если это base64, изолируйте декодирование, чтобы некорректная полезная нагрузка вызывала перехватываемую ошибку. Всегда записывайте сырой ответ в лог-файл перед разбором — так вы сможете отладить проблему, не повторяя потенциально медленный запрос.
Чек-лист диагностики неудачных запросов
Когда запрос завершается неудачей, не спешите переписывать весь вызов. Выполните проверки по порядку и остановитесь на первой неудачной. Каждая проверка изолирует одну переменную.
1. Аутентификация
Сначала проверьте код состояния. 401 означает, что ключ отсутствует, просрочен или имеет неверный формат. Убедитесь, что переменная окружения задана в текущей оболочке, что вы используете префикс Bearer и что в заголовке нет завершающих пробелов.
2. Идентификатор модели
Ошибка «модель не найдена» означает, что значение model не совпадает точно с доступной моделью. Регистр и суффиксы важны. Сравните ваше значение с страницей документации модели посимвольно.
3. Структура полезной нагрузки
400 обычно возникает из-за некорректного тела запроса. Убедитесь, что messages — массив, каждое сообщение содержит role и content, а JSON валиден. Проверка полезной нагрузки через jq или python -m json.tool перед отправкой позволяет поймать синтаксические ошибки.
4. Обработка ответа
Если запрос успешен, но скрипт падает, проблема в коде разбора, а не в API. Запишите сырое тело ответа перед срезами и убедитесь, что путь, который вы читаете, действительно существует. Изображение может вернуться как URL в одном вызове и как base64 в другом, поэтому обрабатывайте его по содержимому, а не по предположению.
5. Таймауты и повторы
Генерация изображений может быть медленной. При таймауте увеличьте клиентский таймаут и повторите запрос один раз. Избегайте повторов при ошибках 4xx, так как они снова завершатся тем же образом.
Полезная привычка: сохраните копию заведомо рабочего запроса и сравнивайте с ним неудачные. Большинство неудач отличаются всего одним полем.
Обёртка в переиспользуемый клиент
Как только вызов работает, оберните его в небольшую функцию, чтобы изменения модели и параметров были сосредоточены в одном месте. Эта обёртка централизованно управляет поиском ключа, заголовками и обработкой ошибок:
import base64
import os
import requests
HIAPI_BASE = "https://api.hiapi.ai/v1"
DEFAULT_MODEL = "qwen-image-2.0-pro"
def generate_image(prompt: str, model: str = DEFAULT_MODEL) -> bytes:
"""Generate an image and return its raw bytes."""
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"model": model,
"messages": [{"role": "user", "content": prompt}],
}
response = requests.post(
f"{HIAPI_BASE}/chat/completions",
headers={"Authorization": f"Bearer {api_key}"},
json=payload,
timeout=120,
)
response.raise_for_status()
content = response.json()["choices"][0]["message"]["content"]
if isinstance(content, str) and content.startswith("http"):
return requests.get(content, timeout=60).content
return base64.b64decode(content)
Код вызова становится одной строкой: open("out.png", "wb").write(generate_image("A ceramic mug on a wooden table")). Если позже вы переключитесь на другую модель изображений или добавите параметры, измените только эту функцию. Идентификатор модели и любые детали параметров находятся на странице модели — вы можете сначала просмотреть сведения о модели qwen-image-2.0-pro, а затем подключиться.
Начните с вызова curl, затем перейдите к скрипту Python и, наконец, к обёртке. Каждый шаг подтверждает меньшую часть, прежде чем вы построите следующий уровень.
Похожие статьи
Все статьи →-
Руководство
kling-image-4.0 на практике: 5 ценных сценариев применения и ключевые моменты интеграции
-
Руководство
Как вызвать gemini-omni-1.1-flash через HiAPI API: руководство по curl и Python
-
Руководство
Как вызвать API преобразования текста в видео veo-3.1: примеры на curl и Python
Практическое руководство по интеграции для разработчиков