Как использовать deepseek-v4-flash-vision-exp через API hiapi: curl, Python и рабочий запрос

deepseek-v4-flash-vision-exp — это модель для работы с текстом и изображениями с возможностями рассуждения на hiapi, доступная через стандартную точку доступа, совместимую с OpenAI: POST /v1/chat/completions. Она одновременно читает изображения и текст, поддерживает JSON-режим и вызов функций/инструментов, а также поддерживает потоковый вывод — и всё это через ту же структуру запроса, что и у любой другой чат-модели hiapi. Это руководство проведёт вас через рабочий запрос, одну легко упускаемую особенность поведения (модель сначала рассуждает, а затем отвечает, и процесс рассуждения расходует ваш бюджет токенов), а также практики для продакшена, о которых стоит знать до запуска.

Что вы построите

Скрипт, который отправляет промпт в deepseek-v4-flash-vision-exp — необязательно с изображением — и читает настоящий ответ, а не только внутренний ход рассуждений.

Предварительные условия: API-ключ hiapi. Получите его в консоли — каждому запросу ниже он нужен в заголовке Authorization.

Минимальный рабочий пример

curl

curl -s -X POST "https://api.hiapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash-vision-exp",
    "messages": [
      { "role": "user", "content": "Say OK and nothing else." }
    ],
    "max_tokens": 200
  }'

Сокращённый ответ выглядит так:

{
  "choices": [
    {
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "OK",
        "reasoning_content": "We need to respond exactly \"OK\" and nothing else. ..."
      }
    }
  ],
  "usage": {
    "completion_tokens": 37,
    "completion_tokens_details": { "reasoning_tokens": 34 },
    "prompt_tokens": 89,
    "total_tokens": 126
  }
}

Здесь важны два поля: message.content — это фактический ответ, а message.reasoning_content — внутренняя цепочка рассуждений модели до того, как она определила этот ответ. usage.completion_tokens_details.reasoning_tokens говорит, сколько бюджета max_tokens израсходовал процесс рассуждения — в этом простом примере 34 из 37 completion-токенов ушли на рассуждения, прежде чем модель написала "OK".

Вот она, та самая ловушка: если задать max_tokens слишком низким, модель может потратить весь бюджет на рассуждения, из-за чего content будет null, а finish_reason — "length". Тот же запрос с max_tokens: 10 возвращает content: null — модель всё ещё думала, когда достигла лимита. Дайте этой модели достаточно места: как минимум 150–300 токенов для коротких ответов и больше для задач, требующих настоящей глубины рассуждений.

Python

import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-your-api-key",
        "Content-Type": "application/json",
    },
    json={
        "model": "deepseek-v4-flash-vision-exp",
        "messages": [
            {"role": "user", "content": "Say OK and nothing else."},
        ],
        "max_tokens": 200,
    },
    timeout=60,
)
resp.raise_for_status()
message = resp.json()["choices"][0]["message"]
print(message["content"])

Визуальный ввод

Чтобы передать изображение вместе с текстом, задайте content как массив типизированных сегментов — image_url принимает любой публично доступный URL изображения:

curl -s -X POST "https://api.hiapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash-vision-exp",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "What color is the dominant background color of this image? One word." },
          { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
        ]
      }
    ],
    "max_tokens": 200
  }'

Для реального тестового изображения модель вернула "Beige", а reasoning_content показал, что она сначала прошла через визуальное описание, прежде чем дать односложный ответ — та же схема «сначала рассуждение, затем ответ», что и в текстовых запросах, только с опорой на изображение.

JSON-режим и вызов инструментов

Структурированный вывод JSON — добавьте response_format: {"type": "json_object"} и упомяните JSON в промпте:

{
  "model": "deepseek-v4-flash-vision-exp",
  "messages": [
    { "role": "user", "content": "Return a JSON object with keys name and age for a fictional person." }
  ],
  "response_format": { "type": "json_object" },
  "max_tokens": 300
}

message.content вернётся в виде разбираемой JSON-строки ({"name": "Alex Doe", "age": 30}), а reasoning_content по-прежнему будет содержать черновик модели — разбирайте только content, никогда не разбирайте reasoning_content.

Вызов функций/инструментов — передайте стандартный массив tools в стиле OpenAI:

{
  "model": "deepseek-v4-flash-vision-exp",
  "messages": [
    { "role": "user", "content": "What is the weather in Tokyo right now? Use the get_weather tool." }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    }
  ],
  "max_tokens": 300
}

Модель ответит с finish_reason: "tool_calls" и массивом tool_calls (содержащим function.name, function.arguments в виде JSON-строки и call_id, который вы передаёте обратно в следующем раунде) — стандартный цикл вызова функций OpenAI работает без изменений.

Рекомендации для продакшена

• Закладывайте бюджет max_tokens на рассуждения, а не только на ответ. Это модель рассуждения — каждый ответ включает процесс reasoning_content перед финальным content, и оба расходуются из одного и того же пула max_tokens. На ранних тестах проверяйте usage.completion_tokens_details.reasoning_tokens, калибруйте безопасный лимит для ваших промптов и всегда проверяйте finish_reason — "length" при content null означает, что вас обрезали посреди размышлений, а не что вы получили настоящий ответ.
• Потоковый вывод работает через stream: true. В отличие от некоторых моделей рассуждения на hiapi с принудительным потоковым выводом, эта модель поддерживает оба режима. В потоковом режиме reasoning_content и content приходят как отдельные поля delta в одном и том же потоке чанков — если вы хотите отображать «размышление» и «ответ» как разные состояния UI, буферизуйте их раздельно.
• Ошибки аутентификации возвращаются явно. Неверный или отозванный ключ возвращает HTTP 401, а в теле ошибки — "code": "permission_denied" и request_id. Ветвите обработку по полю code, а не по совпадению строки сообщения, и прикладывайте request_id при обращении в поддержку.
• Не показывайте reasoning_content конечному пользователю как ответ. Это неструктурированный черновик, а не финальный ответ — особенно в JSON-режиме или при вызове инструментов только content (или tool_calls) предназначены для машинного потребления.
• Визуальный ввод принимает публичные URL, а не встроенный base64. image_url.url должен быть доступен для загрузки серверами hiapi; перед отправкой запроса разместите изображение самостоятельно или используйте URL, который вы контролируете.

Связанные материалы

• Страница модели deepseek-v4-flash-vision-exp — полный справочник параметров и актуальные цены
• Документация API hiapi — аутентификация, другие семейства моделей и полный список точек доступа
• Цены hiapi — ставки за токен для deepseek-v4-flash-vision-exp и всех других моделей
• Руководство по API gpt-6-astra — вторая модель рассуждения на hiapi с иной формой интеграции (только потоковый вывод, Responses API), полезная для сравнения

Часто задаваемые вопросы

Поддерживает ли deepseek-v4-flash-vision-exp визуальный ввод? Да. Отправьте content в виде массива, содержащего сегмент text и один или несколько сегментов image_url, каждый из которых указывает на публично доступный URL изображения. Модель сначала рассуждает об изображении так же, как о тексте, а затем отвечает.

Почему message.content в моём ответе равно null? Ваш max_tokens слишком мал, и процесс рассуждения модели исчерпал весь бюджет до того, как она написала ответ. Проверьте finish_reason — "length" при content: null означает именно этот случай; увеличьте max_tokens и повторите попытку.

Поддерживает ли она JSON-режим? Да, через response_format: {"type": "json_object"}. JSON попадает в message.content в виде строки, которую вы разбираете сами; reasoning_content не является структурированным выводом и в этом сценарии его следует игнорировать.

Поддерживает ли она вызов функций/инструментов? Да, используется стандартный формат массива tools OpenAI. Ответ, инициирующий инструмент, возвращает finish_reason: "tool_calls" и массив tool_calls, содержащий имя функции и аргументы.

Можно ли получать ответ в потоковом режиме? Да — установите "stream": true и обрабатывайте события chat.completion.chunk. И content, и reasoning_content передаются потоком как отдельные поля delta в одном и том же чанке.

Как выглядит ошибка аутентификации? HTTP 401, тело JSON-ответа содержит "type": "hiapi_error", "code": "permission_denied", понятное человеку поле message и request_id, который можно передать в поддержку (если проблема сохраняется).