Alibaba Cloud API

Стабильный контракт — Проверено по документации Alibaba Cloud 29.07.2026

Для LLM и изображений клиентский endpoint определяет публичный формат ответа. NeuroAPI выбирает подходящий Alibaba Cloud workspace, преобразует запрос во внутренний/provider формат и возвращает результат в том же API-контракте, который выбрал клиент.

1 · Клиент

Отправляет Chat Completions, Responses, OpenAI Images или video request.

2 · NeuroAPI

Проверяет модель, лимиты и баланс, фиксирует цену, выбирает регион и вызывает Alibaba.

3 · Ответ

Нормализуется обратно в выбранный клиентом формат; provider envelope наружу не просачивается.

Важно: Формат сохраняется, но набор возможностей определяется связкой модель + endpoint + регион. Наличие модели в GET /v1/models не означает поддержку каждого tool, режима изображения или media combination.

Матрица API

Информация: ASR намеренно не указан: совместимый multimodal chat, асинхронная расшифровка файлов и realtime ASR имеют разные протоколы и тарификацию по секундам аудио. Пока этот billing contract не опубликован, не используйте Alibaba ASR через универсальный endpoint.

LLM: формат запроса сохраняется

Запрос к /v1/chat/completions всегда получает Chat Completions envelope. Запрос к /v1/responses всегда получает Responses envelope. Это относится и к обычным ответам, и к streaming: клиенту не нужно распознавать внутренний API Alibaba.

curl https://neuroapi.host/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.7-flash",
    "messages": [
      {"role": "user", "content": "Составь план релиза в трёх пунктах"}
    ],
    "stream": false
  }'

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "model": "qwen3.7-flash",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 72,
    "total_tokens": 90
  }
}

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://neuroapi.host/v1",
)

response = client.responses.create(
    model="qwen3.8-max",
    input="Какая погода в Иркутске и что надеть?",
    tools=[{"type": "web_search"}],
    store=False,
)

print(response.output_text)
print(response.usage)

{
  "id": "resp_...",
  "object": "response",
  "status": "completed",
  "model": "qwen3.8-max",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{"type": "output_text", "text": "..."}]
    }
  ],
  "usage": {
    "input_tokens": 24,
    "output_tokens": 146,
    "total_tokens": 170
  }
}

Streaming

Для Chat Completions используйте stream: true и собирайте chat.completion.chunk. Responses возвращает события response.output_text.delta, tool events и финальный response.completed. Не смешивайте парсеры этих потоков.

Function tools

Клиентские function tools поддерживаются в обоих форматах, если выбранная модель умеет tool calling. Выполняет функцию ваше приложение; затем оно отправляет результат обратно в формате того же API.

Structured output и reasoning

Передавайте response_format, reasoning/thinking и multimodal content только моделям, у которых эти поля указаны в карточке. Непредставимое поле отклоняется до отправки либо возвращает безопасную 400, а не молча теряется.

Responses state

store: true, previous_response_id и resource endpoints закрепляются за создавшим workspace. Не меняйте модель/ключ между продолжениями. Для максимальной переносимости используйте store: false и храните историю у себя.

Граница протоколов Qwen3.8 Max

Chat Completions принимает текст, изображения и видео. Ставьте partial: true только в последнее сообщение assistant и отключайте thinking. Responses принимает текст и изображения, но не аудио и видео — для видео используйте Chat. Несовместимый запрос получает безопасную 400 до платной отправки провайдеру.

Context cache: как получить больше hits

NeuroAPI не кеширует готовые ответы. Он закрепляет одинаковый стабильный префикс за одним дешёвым Alibaba workspace. Ставьте system/developer инструкции, tools и schema в начало, а изменяющийся пользовательский текст — в конец.

Cache-тариф зависит от модели. Для Qwen3.8 implicit hit стоит 12,5% обычного input, explicit hit — 8,5%, а создание explicit/session cache — 125%. Session cache требует минимум 1024 токена и имеет скользящий TTL 5 минут. Он выгоден для повторяющихся длинных сессий, но не для одиночных запросов.

Смотрите prompt_tokens_details.cached_tokens в Chat и input_tokens_details.cached_tokens в Responses. Клиентские cache_control: {"type":"ephemeral"} блоки сохраняются.

Важно: Qwen3.8 Responses поддерживает capability-gated инструменты web_search, code_interpreter, web_extractor, web_search_image и image_search. Задавайте общий max_tool_calls. Для web_extractor в запросе также нужен web_search, а code_interpreter нельзя объединять с клиентскими function tools. Вызовы и токены всех внутренних шагов считаются по terminal usage провайдера.

Изображения: OpenAI Images снаружи

NeuroAPI преобразует OpenAI Images request в Qwen Image, Wan Image или Z-Image API и возвращает единый data[]. Для response_format: "url" приходит временная ссылка; для b64_json NeuroAPI безопасно скачивает provider result и возвращает Base64.

curl https://neuroapi.host/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0-pro",
    "prompt": "Редакционный натюрморт с матовым чёрным чайником",
    "size": "1024x1024",
    "n": 1,
    "response_format": "url"
  }'

curl https://neuroapi.host/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=qwen-image-2.0-pro" \
  -F "prompt=Замени фон на светлую студию, объект не меняй" \
  -F "image=@input.png" \
  -F "response_format=b64_json"

{
  "created": 1785000000,
  "data": [
    {
      "url": "https://temporary-result.example/...",
      "revised_prompt": "..."
    }
  ]
}

Generation

prompt, size, n, response_format и поддерживаемые model-specific параметры.

Editing

Multipart upload, публичный URL или data URL. Qwen 2.0 принимает до трёх изображений; Wan 2.7 может поддерживать больше — проверяйте карточку конкретной модели.

Model-specific extras

Доступны, где поддерживаются: negative_prompt, prompt_extend, thinking_mode, watermark, seed, bbox_list, color_palette.

Важно: NeuroAPI принимает image upload до 20 MiB, но модель может иметь более строгий предел (например, 10 MiB у некоторых Qwen Image Edit). Поддерживаемые форматы: JPG/JPEG, PNG, WEBP, GIF, BMP и TIFF. Для GIF обрабатывается только первый кадр.

Важно: Ссылки Alibaba на сгенерированные изображения действуют только 24 часа. NeuroAPI best-effort переносит URL в долговечное хранилище. Если ответ содержит X-NeuroAPI-Media-Expires-In: 86400, скачайте результат сразу.

Видео: два публичных формата

Для общей интеграции используйте OpenAI video lifecycle. Если нужна полная структура Alibaba input/parameters, используйте prefixed native routes. Оба варианта создают одну долговечную задачу NeuroAPI, используют одинаковый billing snapshot и не допускают бесплатного повторного create после принятия.

OpenAI video

Стабильный

curl https://neuroapi.host/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-t2v",
    "prompt": "Камера медленно движется вдоль туманного хвойного леса",
    "seconds": 5,
    "size": "1280x720"
  }'

curl https://neuroapi.host/v1/videos/{id} \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -L https://neuroapi.host/v1/videos/{id}/content \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output result.mp4

Alibaba-compatible native video

Бета — Provider-compatible

Native create сохраняет документированные Alibaba maps и подменяет только выбранную upstream-модель после model mapping. Поддерживаются T2V, I2V и R2V модели Wan/HappyHorse; допустимые duration, resolution, media types и сочетания зависят от модели.

curl https://neuroapi.host/alibaba/api/v1/services/aigc/video-generation/video-synthesis \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-i2v",
    "input": {
      "prompt": "Лёгкий ветер колышет листья, камера неподвижна",
      "media": [
        {"type": "image", "url": "https://example.com/first-frame.png"}
      ]
    },
    "parameters": {
      "duration": 5,
      "resolution": "720P",
      "prompt_extend": true,
      "watermark": false
    }
  }'

curl https://neuroapi.host/alibaba/api/v1/tasks/{task_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "output": {
    "task_id": "3f0d...",
    "task_status": "SUCCEEDED",
    "video_url": "https://temporary-result.example/result.mp4"
  }
}

Важно: Если create вернул успешный 2xx или task_id, больше не повторяйте POST. Сетевой обрыв после отправки может быть неоднозначным: новая попытка способна создать второе платное видео. Сохраняйте ID до перехода на polling и повторяйте только GET.

Важно: Alibaba хранит video task_id и result URL 24 часа. До завершения фонового зеркалирования task содержит url_expires_at. Рекомендуемый polling — около 15 секунд; provider task query ограничен 20 QPS на Alibaba Cloud account.

Embeddings, rerank и TTS

Эти API также нормализуются в публичные NeuroAPI/OpenAI-compatible контракты. Биллинг фиксируется до отправки и финализируется по provider usage; если успешный legacy response не содержит usage, используется сохранённая оценка запроса.

curl https://neuroapi.host/v1/embeddings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"text-embedding-v4","input":["Первый текст","Второй текст"]}'

curl https://neuroapi.host/v1/rerank \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"qwen3-rerank",
    "query":"Как настроить резервное копирование?",
    "documents":["Инструкция по backup","Описание тарифов"]
  }'

curl https://neuroapi.host/v1/audio/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"qwen3-tts-flash",
    "input":"Добро пожаловать в NeuroAPI",
    "voice":"Cherry",
    "response_format":"wav"
  }' --output speech.wav

Информация: Alibaba Qwen3 TTS в текущем контракте возвращает WAV. Для другого response_format используйте модель/провайдера, который явно его поддерживает, или перекодируйте файл после получения.

Ошибки и что делать

Обрабатывайте HTTP status и стабильный error.code (для OpenAI routes) либо top-level code (для Alibaba video routes). Не анализируйте текст сообщения: он может уточняться, а сырые provider/internal детали намеренно скрыты.

Регион или ключ не совпадает

Пользователь увидит безопасную ошибку авторизации/доступности. Оператор должен проверить, что API key, workspace host, provider region и модель созданы в одном регионе. Не пытайтесь исправлять это client retry.

Moderation и IP

DataInspectionFailed и IPInfringementSuspect нормализуются в moderation_blocked. Уберите запрещённый контент, бренды/персонажей либо спорное исходное медиа; автоматический retry бессмысленен.

Важно: Для обычного LLM POST допустим ограниченный retry только после явных 429/502/503/504 до получения ответа. Для Images и особенно async Video не ставьте общий автоматический retry: после принятия задачи повторяется polling, а не create.

Production checklist

1. Получайте доступные ID через GET /v1/models тем же NeuroAPI key.
2. Разделяйте Chat, Responses и video parsers; не определяйте формат по модели.
3. Задайте connect/read timeout отдельно; для длинных LLM ответов предпочитайте streaming.
4. Храните video task ID и состояние в БД до завершения задачи.
5. Скачивайте image/video result в своё хранилище сразу, не позднее 24 часов.
6. Логируйте timestamp, модель, endpoint, HTTP status и безопасный code без API-ключей и исходных приватных медиа.

Официальная документация Alibaba Cloud

• Text Generation API reference ↗
• OpenAI-compatible Responses ↗
• Image generation and production limits ↗
• Wan text-to-video API ↗
• Async task retention and limits ↗
• Regions, keys, and workspace Base URLs ↗