Alibaba Native API

Beta · Контракт реализации обновлён 24 октября 2026 года

Alibaba Native — отдельный клиентский формат NeuroAPI для приложений с DashScope SDK или структурой model / input / parameters. Он сохраняет нативные ответы output / usage / request_id. Ключ и баланс остаются вашими ключом и балансом NeuroAPI; отдельный аккаунт Alibaba Cloud не нужен.

Beta относится к совместимости формата: поддерживаемый набор полей ограничен описанным контрактом. Наличие модели в каталоге не означает поддержку любого нативного endpoint. Перед интеграцией проверьте конкретную модель и тариф.

Для готового приложения с OpenAI SDK используйте OpenAI-совместимые API. Для векторов и ранжирования выбирайте API своей задачи: эти модели не отвечают через Chat Completions или Responses.

Адрес, ключ и доступность

Базовый URL DashScope SDK:

https://neuroapi.host/alibaba/api/v1

Авторизация HTTP: Authorization: Bearer $NEUROAPI_KEY. Используйте ключ выбранного тарифа NeuroAPI. Не подставляйте адрес OpenAI /v1 в DashScope SDK: SDK сам добавляет services/... к своему базовому адресу.

Проверьте карточку модели. В GET /api/pricing поле task_type описывает специальную задачу (embedding или rerank), а alibaba_native_endpoints перечисляет доступные нативные пути по физическим тарифам default (Пилот) и plus (Оптимальный). Например:

{
  "model_name": "text-embedding-v4",
  "task_type": "embedding",
  "alibaba_native_endpoints": {
    "plus": ["/alibaba/api/v1/services/embeddings/text-embedding/text-embedding"]
  }
}

Пример показывает форму метаданных, а не неизменную гарантию доступности. Отсутствующее поле не подтверждает поддержку Native. GET /v1/models показывает доступные ключу модели, но не заменяет проверку пары «модель + API».

Выберите endpoint задачи

Все пути в таблице используют метод POST и домен https://neuroapi.host.

У разных версий одного семейства могут быть разные пути. Например, qwen-plus использует текстовую структуру, а qwen3.7-plus — мультимодальную. Следуйте пути, опубликованному для конкретного ID модели и тарифа, а не названию семейства. Подмена пути без изменения структуры запроса приводит к ошибке.

Один мультимодальный путь обслуживает несколько задач: текст, изображения, Omni, поддерживаемый синтез и распознавание речи. Тип запроса и конкретная модель должны соответствовать задаче. Само совпадение URL не разрешает другую операцию.

Поддержка в исходном коде и её доступность на вашем тарифе — разные вещи. Новые возможности появляются в метаданных модели после проверки и публикации. Наличие примера ниже не обещает, что любая модель или регион уже активированы. Для нативного создания видео и проверки его задачи используйте руководство Alibaba Cloud и Video API.

Генерация текста

Сначала убедитесь, что текстовый endpoint опубликован для выбранного тарифа. messages и prompt — альтернативы: в одном запросе выбирайте один вид входа. Для нового кода удобнее messages и result_format: "message".

curl https://neuroapi.host/alibaba/api/v1/services/aigc/text-generation/generation \
  -H "Authorization: Bearer $NEUROAPI_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen-plus",
    "input": {"messages": [{"role": "user", "content": "Объясни API одним предложением."}]},
    "parameters": {"result_format": "message", "max_tokens": 128}
  }'

Сокращённый пример ответа:

{
  "request_id": "request-example",
  "output": {
    "choices": [{"finish_reason": "stop", "message": {"role": "assistant", "content": "API позволяет приложениям обмениваться данными."}}]
  },
  "usage": {"input_tokens": 18, "output_tokens": 12, "total_tokens": 30}
}

При result_format: "text" читайте output.text. Не разбирайте нативный ответ как choices[0].message верхнего уровня OpenAI.

Python: DashScope SDK

Установите актуальный SDK командой python -m pip install --upgrade dashscope. Секрет храните в переменной окружения NEUROAPI_KEY.

Для SDK 2 используйте клиент с явным protocol="native":

import os
from dashscope import Client

with Client(
    protocol="native",
    base_url="https://neuroapi.host/alibaba/api/v1",
    api_key=os.environ["NEUROAPI_KEY"],
    max_retries=0,
) as client:
    response = client.chat.completions.create(
        model="qwen-plus",
        messages=[{"role": "user", "content": "Объясни API одним предложением."}],
        max_tokens=128,
        enable_thinking=False,
        parameters={"result_format": "message"},
    )
    print(response.model_dump())

Существующий интерфейс Generation.call также поддерживается:

import os
import dashscope

dashscope.base_http_api_url = "https://neuroapi.host/alibaba/api/v1"
response = dashscope.Generation.call(
    api_key=os.environ["NEUROAPI_KEY"],
    model="qwen-plus",
    messages=[{"role": "user", "content": "Объясни API одним предложением."}],
    result_format="message",
    max_tokens=128,
)
if response.status_code != 200:
    raise RuntimeError(response.code, response.message)
print(response.output)
print(response.usage)

Мультимодальная генерация

Даже текст передаётся массивом блоков. Для изображения добавьте отдельный блок {"image": "https://..."} рядом с текстовым. Модель должна поддерживать изображения; URL должен быть публичным HTTPS. В обычном JSON не передавайте локальные пути или внутренние адреса. Для локального файла используйте SDK-загрузку, описанную ниже. Допустимые размеры и типы проверяются до обработки.

curl https://neuroapi.host/alibaba/api/v1/services/aigc/multimodal-generation/generation \
  -H "Authorization: Bearer $NEUROAPI_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen3.7-plus",
    "input": {"messages": [{"role": "user", "content": [{"text": "Объясни API одним предложением."}]}]},
    "parameters": {"max_tokens": 128, "enable_thinking": false}
  }'

В SDK этому пути соответствует dashscope.MultiModalConversation.call:

import os
import dashscope

dashscope.base_http_api_url = "https://neuroapi.host/alibaba/api/v1"
response = dashscope.MultiModalConversation.call(
    api_key=os.environ["NEUROAPI_KEY"],
    model="qwen3.7-plus",
    messages=[{"role": "user", "content": [{"text": "Объясни API одним предложением."}]}],
    enable_thinking=False,
    max_tokens=128,
)
if response.status_code != 200:
    raise RuntimeError(response.code, response.message)
print(response.output)

enable_thinking и thinking_budget зависят от модели. Не добавляйте их универсально ко всем моделям. Учитывайте токены рассуждений в бюджете ответа.

Поддерживающие видеовход модели принимают блок video с публичной HTTPS-ссылкой или массивом ссылок на кадры. Для массива действует предел 128 кадров на запрос; изображения и кадры суммарно ограничены 16 МиБ после декодирования. Параметры min_pixels, max_pixels, fps, vl_high_resolution_images и vl_enable_image_hw_output доступны только там, где их принимает модель. При включённом выводе размеров image_hw приходит в массиве содержимого ответа, в том числе в последнем событии SSE. Пределы видеовхода генерации не означают поддержку видеоэмбеддингов.

Потоковая выдача SSE

SSE используется только для генерации, а не для векторизации и ранжирования. В HTTP включите X-DashScope-SSE: enable. Для выдачи приращений задайте parameters.incremental_output: true.

curl -N https://neuroapi.host/alibaba/api/v1/services/aigc/text-generation/generation \
  -H "Authorization: Bearer $NEUROAPI_KEY" \
  -H 'Content-Type: application/json' \
  -H 'X-DashScope-SSE: enable' \
  -d '{
    "model": "qwen-plus",
    "input": {"messages": [{"role": "user", "content": "Назови три применения API."}]},
    "parameters": {"result_format": "message", "incremental_output": true, "max_tokens": 128}
  }'

Читайте нативные SSE-события и поля output, usage, request_id. incremental_output: true означает приращения; без него промежуточные ответы могут содержать накопленный текст, который нельзя безусловно дописывать заново. Финальное состояние определяется finish_reason и завершающими данными. Не требуйте OpenAI delta или маркер [DONE] от нативного потока.

Когда несколько вариантов ответа разрешены параметром n, каждый вариант собирается отдельно по index. Полный массив без индексов имеет стабильный порядок; неполные массивы без индексов не позволяют надёжно сопоставить варианты. Поток завершён только после финального состояния всех вариантов и итогового usage. Повтор одинакового накопленного снимка не является новым текстом.

В SDK используйте stream=True, incremental_output=True и перебирайте ответы Generation.call или MultiModalConversation.call. Проверяйте код каждого ответа. После начала выдачи ошибка может прийти событием error: HTTP-статус уже начатого потока не меняется.

import os
import dashscope

dashscope.base_http_api_url = "https://neuroapi.host/alibaba/api/v1"
chunks = dashscope.Generation.call(
    api_key=os.environ["NEUROAPI_KEY"],
    model="qwen-plus",
    messages=[{"role": "user", "content": "Назови три применения API."}],
    result_format="message",
    max_tokens=128,
    stream=True,
    incremental_output=True,
)
for chunk in chunks:
    if chunk.status_code != 200:
        raise RuntimeError(chunk.code, chunk.message)
    for choice in chunk.output.get("choices", []):
        print(choice.get("message", {}).get("content", ""), end="", flush=True)

Для поддерживающих его моделей max_completion_tokens задаёт общий бюджет ответа, включая рассуждения. Выбирайте один способ ограничения согласно модели; не отправляйте одновременно конфликтующие лимиты. Для первого короткого запроса к гибридной модели удобно отключить мышление через enable_thinking: false и задать небольшой max_tokens.

Дополнительные параметры текста

Параметры зависят от модели. Неподдерживаемая комбинация возвращает ошибку до начала платной обработки, вместо молчаливого игнорирования.

n увеличивает бюджет и суммарный выход, но не умножает вход. В usage возвращается уже общий расход запроса: не умножайте его на n повторно. Для n > 1 используйте result_format: "message". Значение partial: true у последнего сообщения ассистента позволяет продолжать незавершённый префикс только там, где модель поддерживает такой режим.

Функции приложения

Передавайте определения в parameters.tools и используйте result_format: "message". Для запрета функций задайте tool_choice: "none"; для конкретной функции — {"type":"function","function":{"name":"lookup"}}. required допустим только у поддерживающих его моделей; Qwen этот режим не поддерживает. Принудительный выбор функции нельзя сочетать с режимом мышления, если модель запрещает такую комбинацию.

В истории сохраняйте tool_calls[].id, index, имя, JSON-объект аргументов и ответ роли tool с соответствующим tool_call_id. Вызов исполняет ваше приложение после проверки аргументов; NeuroAPI не запускает произвольный код из функции. Для нескольких вызовов включите parallel_tool_calls: true.

Фрагменты вызовов не выдаются до проверки законченной структуры. При обязательном вызове весь результат может прийти одним финальным событием: обычный текст не считается выполнением обязательной функции. Параметр tool_stream не отменяет эту проверку. Причина length не подтверждает завершённый вызов; stop у мультимодальной модели может завершать проверенную функцию наряду с tool_calls.

Перевод Qwen-MT

Для опубликованных qwen-mt-plus, qwen-mt-flash, qwen-mt-lite используется текстовый путь с одним пользовательским сообщением и parameters.translation_options. Укажите source_lang и target_lang полными английскими названиями языков; source_lang: "auto" включает определение языка. Необязательные terms, tm_list и domains задают терминологию, память перевода и предметную область. Текст предметной области передавайте на английском языке.

В SSE Flash и Lite всегда возвращают приращения, Plus — накопленный текст. Этот режим фиксирован моделью; противоположный incremental_output отклоняется.

Текстовые эмбеддинги

text-embedding-v4 и qwen3.7-text-embedding превращают текст в векторы для поиска, группировки и RAG. Это не модели генерации ответа. В HTTP используется input.texts, а в SDK — аргумент input.

curl https://neuroapi.host/alibaba/api/v1/services/embeddings/text-embedding/text-embedding \
  -H "Authorization: Bearer $NEUROAPI_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "text-embedding-v4",
    "input": {"texts": ["Документ для поиска", "Ещё один документ"]},
    "parameters": {"dimension": 1024, "text_type": "document", "output_type": "dense"}
  }'

import os
import dashscope

dashscope.base_http_api_url = "https://neuroapi.host/alibaba/api/v1"
response = dashscope.TextEmbedding.call(
    api_key=os.environ["NEUROAPI_KEY"],
    model="qwen3.7-text-embedding",
    input=["Документ для поиска"],
    dimension=1024,
    text_type="document",
    output_type="dense",
)
if response.status_code != 200:
    raise RuntimeError(response.code, response.message)
print(response.output["embeddings"])

В output.embeddings dense-вектор находится в embedding, а позиция текста — в text_index. Для sparse-вывода используйте output_type: "sparse" или "dense&sparse": разреженные значения возвращаются в sparse_embedding.

Для индексации используйте text_type: "document", для поискового запроса — "query". Необязательный instruct применяется вместе с text_type: "query". Размерность, модель и способ индексации должны совпадать у документов и запросов. Смена embedding-модели обычно требует переиндексации документов.

Пустые тексты не принимаются. Указание dimension не увеличивает лимит входа. Не отправляйте stream, max_tokens или messages на embedding endpoint.

Мультимодальные эмбеддинги

tongyi-embedding-vision-plus и tongyi-embedding-vision-flash строят независимые векторы для элементов input.contents. Возможности зависят от точной версии: исходные модели и новые снимки имеют разные контракты. Видео не поддерживается в произвольной модели только по совпадению имени семейства.

Документированные языки текстового ввода этих двух моделей — английский и китайский. Для первого запроса используйте английский текст, как в примере; при работе с другими языками отдельно проверяйте качество своего поиска.

curl https://neuroapi.host/alibaba/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding \
  -H "Authorization: Bearer $NEUROAPI_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "tongyi-embedding-vision-plus",
    "input": {"contents": [{"text": "White sports shoes"}]}
  }'

Чтобы получить вектор изображения, вместо текстового элемента передайте {"image": "https://..."} с публичным HTTPS-адресом или поддерживаемым Data URI. Не смешивайте несколько модальностей внутри одного элемента. Каждый результат в output.embeddings содержит index, type и embedding.

Для Data URI принимается base64 JPEG, PNG или BMP: до 3 МиБ после декодирования. Содержимое и заявленный MIME-тип должны совпадать. Передача по ссылке также должна соответствовать ограничениям формата и размера выбранной модели.

Допускается от 1 до 20 элементов. Для группы изображений используйте один элемент {"multi_images": ["https://...", "https://..."]} с 1–8 изображениями; не смешивайте его с text или image внутри того же элемента. Всего в запросе допускается не более 8 изображений, включая все image и multi_images, и не более 16 МиБ декодированных изображений в сумме.

import os
import dashscope

dashscope.base_http_api_url = "https://neuroapi.host/alibaba/api/v1"
response = dashscope.MultiModalEmbedding.call(
    api_key=os.environ["NEUROAPI_KEY"],
    model="tongyi-embedding-vision-flash",
    input=[{"text": "White sports shoes"}],
)
if response.status_code != 200:
    raise RuntimeError(response.code, response.message)
print(response.output["embeddings"])

Текст ограничен 1024 токенами на элемент. Размерности фиксированы текущим контрактом исходных моделей: 1152 у Plus и 768 у Flash. Произвольная размерность не разрешается; для новых режимов нужен отдельный профиль ниже.

Для отдельно опубликованных qwen3-vl-embedding, qwen2.5-vl-embedding и соответствующих снимков Tongyi доступны дополнительные режимы. qwen3-vl поддерживает независимые векторы либо fusion; qwen2.5-vl использует fusion. Fusion объединяет модальности одного входа в один вектор и не является обычным списком независимых embedding-запросов.

Поддерживаемое видео задаётся input.contents[].video либо предусмотренными моделью кадрами. NeuroAPI сохраняет исходные байты до выполнения; предел видеовхода — 300 секунд и 50 МиБ. Только в подходящем профиле допустимы fps от 0 до 1, res_level от 0 до 3 и max_video_frames от 1 до 64. Фиксированные размерности и сочетания модальностей проверяются по модели. Проекция fusion в обычный OpenAI /v1/embeddings не поддерживается: для него используйте Native. Не переносите пределы одного семейства на другое.

Ранжирование документов

Мультимодальный qwen3-vl-rerank имеет отдельную типизированную форму: запрос — текст или изображение, кандидаты — текст, изображение или видео. Видео в самом запросе ранжирования не поддерживается. Для этого режима нужны собственные опубликованные возможности и цены: обычное текстовое ранжирование не включает их автоматически. qwen3.7-rerank остаётся текстовой задачей.

qwen3-rerank принимает поисковый запрос и кандидатов, возвращает индексы документов и оценки релевантности. Он не создаёт новый ответ на вопрос.

curl https://neuroapi.host/alibaba/api/v1/services/rerank/text-rerank/text-rerank \
  -H "Authorization: Bearer $NEUROAPI_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen3-rerank",
    "input": {
      "query": "Как сменить пароль?",
      "documents": ["Откройте настройки аккаунта.", "Прогноз погоды на завтра."]
    },
    "parameters": {"top_n": 1, "return_documents": true}
  }'

import os
import dashscope

dashscope.base_http_api_url = "https://neuroapi.host/alibaba/api/v1"
response = dashscope.TextReRank.call(
    api_key=os.environ["NEUROAPI_KEY"],
    model="qwen3-rerank",
    query="Как сменить пароль?",
    documents=["Откройте настройки аккаунта.", "Прогноз погоды на завтра."],
    top_n=1,
    return_documents=True,
)
if response.status_code != 200:
    raise RuntimeError(response.code, response.message)
print(response.output["results"])

Элемент output.results содержит index, relevance_score и, при return_documents: true, document.text. По index сопоставляйте результат с исходным документом. Оценка релевантности не является вероятностью истинности.

Текущие ограничения NeuroAPI: до 500 документов, до 4000 токенов в запросе и каждом документе; совокупный вход — до 120000 токенов. Для расчёта входа запрос учитывается для каждого кандидата:

вход = токены_запроса × число_документов + сумма_токенов_документов

Необязательный instruct также входит в бюджет. top_n ограничивает число возвращаемых результатов, но не отменяет обработку переданных документов.

Изображения и асинхронные задачи

Генерация изображений использует тот же путь /alibaba/api/v1/services/aigc/multimodal-generation/generation, но принимает запрос опубликованной модели изображений. Поддерживаются модельные параметры size, n, negative_prompt, seed, watermark и применимые расширения. Значения размеров и количество результатов различаются у моделей: не переносите настройки текстового запроса на изображение.

Для Qwen-image-2.0 допускается до 3 входных изображений и до 6 результатов. У Wan2.7 — до 9 входных изображений и до 4 обычных результатов; последовательный режим имеет отдельный предел до 12. Z-image-turbo принимает только текст и один результат. Дополнительные bbox_list, color_palette, thinking_mode, enable_sequential проверяются по модели и комбинации параметров. Для входа генерации изображений действует суммарный предел 32 МиБ и собственный предел каждого файла: до 10 МиБ у Qwen, до 20 МиБ у Wan. Временные ссылки SDK имеют более строгий общий предел 16 МиБ при подстановке содержимого.

Обычный вызов возвращает JSON с готовыми изображениями. Для фоновой обработки передайте X-DashScope-Async: enable; SSE для создания изображений не используется.

curl https://neuroapi.host/alibaba/api/v1/services/aigc/multimodal-generation/generation \
  -H "Authorization: Bearer $NEUROAPI_KEY" \
  -H 'Content-Type: application/json' \
  -H 'X-DashScope-Async: enable' \
  -d '{
    "model": "qwen-image-2.0",
    "input": {"messages": [{"role": "user", "content": [{"text": "Нарисуй маяк у моря."}]}]},
    "parameters": {"n": 1, "size": "2048*2048"}
  }'

Сохраните output.task_id из ответа и проверяйте состояние:

curl "https://neuroapi.host/alibaba/api/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $NEUROAPI_KEY"

Возможные состояния: PENDING, RUNNING, SUCCEEDED, FAILED, CANCELED, UNKNOWN. Готовые изображения находятся в output.choices[].message.content[].image. Для задач изображений результат хранится один час после завершения; каждый опрос выдаёт свежие временные ссылки. После срока хранения возвращается UNKNOWN без ссылок: это не новая генерация и не повторное списание. Путь /tasks/{id} общий для поддерживаемых задач изображений и видео; идентификатор не даёт доступ к чужому результату или другому рабочему пространству.

Omni: текст и аудио в одном запросе

Опубликованные qwen3.5-omni-plus, qwen3.5-omni-flash, qwen3-omni-flash принимают клиентский Native-формат через мультимодальный путь. Для них требуется SSE. Пользовательское содержимое может включать текст, изображения, аудио и поддерживаемое видео; каждое поле проверяется как отдельная модальность.

Для текстового ответа выберите modalities: ["text"]. Для аудио нужны modalities: ["text", "audio"], поддерживаемый голос, audio.format: "wav" и явно заданный incremental_output: true. Накопленное аудио не поддерживается. В ответе читайте нативные блоки text и audio, а не OpenAI delta. Не складывайте общий usage с его детализацией по тексту, изображениям и аудио.

Возможности Omni имеют собственные ограничения. Поддержка текстовых функций не означает поддержку любого параметра обычной LLM: неподходящие response_format, tool_stream, настройки истории мышления или logprobs отклоняются. Поддерживаемый поиск — отдельная модельная возможность с отдельной оплатой; она не включает произвольные плагины или выполнение кода.

Синтез и распознавание речи

Синтез речи существующего семейства Qwen3 TTS использует мультимодальный путь: input.text, обязательный input.voice, необязательный language_type. Текст ограничен 600 символами; инструкции доступны только соответствующим Instruct-моделям. JSON возвращает output.audio.url, SSE — аудиофрагменты. Расход определяется символами текста. Другие семейства используют собственные пути и протоколы ниже; совместимость одного семейства не разрешает остальные.

Для короткого распознавания предусмотрен отдельный контракт qwen3-asr-flash и поддерживаемых снимков. Он появляется в каталоге только после публикации модели с корректной ценой за секунду аудио. Путь остаётся мультимодальным, вход — одно пользовательское сообщение с одним audio; перед ним можно передать системный текст контекста до 4096 символов. Доступны asr_options.language, asr_options.enable_itn, incremental_output.

Аудио передаётся публичной HTTPS-ссылкой, через поддерживаемую SDK-загрузку или base64 Data URI: до 10 МиБ после кодирования в Base64 и до 300 секунд. Для ссылок применяется тот же предел после подготовки аудио. Результат — текст в output.choices, расход — usage.seconds. Это секунды, а не скрытая конвертация в токены. Длительные файловые задачи и WebSocket используют отдельные контракты ниже.

Файловое распознавание речи

Это фоновая операция: сначала создайте задачу, затем сохраните её ID и опросите /alibaba/api/v1/tasks/{id}. Доступны только опубликованные модели с проверенной ценой за секунду: например, соответствующие версии Paraformer и Fun-ASR. Совпадение названия семейства не заменяет проверку доступности.

curl https://neuroapi.host/alibaba/api/v1/services/audio/asr/transcription \
  -H "Authorization: Bearer $NEUROAPI_KEY" \
  -H 'Content-Type: application/json' \
  -H 'X-DashScope-Async: enable' \
  -H "Idempotency-Key: $NEUROAPI_IDEMPOTENCY_KEY" \
  -d '{
    "model": "fun-asr",
    "input": {"file_urls": ["https://example.com/audio.wav"]},
    "parameters": {"channel_id": [0], "language_hints": ["ru"]}
  }'

Задайте NEUROAPI_IDEMPOTENCY_KEY один раз для этой операции и сохраните его. В повторе той же операции используйте тот же ключ и то же тело; для нового аудио создайте новый ключ. Нельзя подменять им обычный ключ авторизации.

В одном запросе передаётся один файл: до 2 ГиБ и 12 часов. NeuroAPI проверяет фактическое аудио, длительность и выбранные дорожки и сохраняет закрытую копию до выполнения. Это отдельный путь загрузки: предел временных SDK-файлов 16 МиБ не превращается в лимит всей файловой расшифровки. Две выбранные дорожки оплачиваются как два обрабатываемых аудиопотока.

Готовая расшифровка доступна по временной ссылке output.results[].transcription_url; форма output.result зависит от модели. Частичный сбой подзадачи не выдаётся за полностью готовую расшифровку. Результат хранится 24 часа; скачайте его заранее. Фоновая задача продолжает выполняться после отключения клиента, повторно её создавать не нужно.

Модели filetrans с оплатой входных и выходных токенов пока недоступны, если для них не подтверждён конечный бюджет результата. Это относится и к неопубликованным сочетаниям Qwen3 filetrans. Чужие vocabulary_id и другие идентификаторы словарей не дают доступ к ресурсам: поддержка account-wide hotword API этим руководством не заявляется.

Собственные словари распознавания

Для отдельно разрешённых ASR-моделей доступен POST /alibaba/api/v1/services/audio/asr/customization с model: "speech-biasing". Действия: create_vocabulary, list_vocabulary, query_vocabulary, update_vocabulary, delete_vocabulary.

curl https://neuroapi.host/alibaba/api/v1/services/audio/asr/customization \
  -H "Authorization: Bearer $NEUROAPI_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $NEUROAPI_IDEMPOTENCY_KEY" \
  -d '{
    "model": "speech-biasing",
    "input": {
      "action": "create_vocabulary",
      "target_model": "paraformer-v2",
      "prefix": "neuroapi",
      "vocabulary": [{"text": "NeuroAPI", "weight": 4, "lang": "en"}]
    }
  }'

Используйте возвращённый идентификатор nvocab_... как vocabulary_id в соответствующей модели ASR. Словарь привязан к целевой модели и владельцу; ID из внешнего аккаунта не принимаются. Список содержит только свои словари, доступные текущему ключу. Для изменения передаётся тот же Vocabulary ID, а не новый target_model для переноса ресурса.

Управление словарём бесплатно. Доступ требует отдельной публикации и разрешения сервиса; произвольная модель или регион его не включают. Число словарей ограничено, обновления разделяются минимум пятью минутами. Нельзя изменять или удалять словарь, используемый выполняющимся ASR. Сохраните Idempotency-Key для мутации; неопределённый результат не даёт разрешения создать ещё один словарь с новым ключом.

Асинхронные эмбеддинги из файла

text-embedding-async-v1 и text-embedding-async-v2 — отдельные модели для файла UTF-8, где каждая строка является отдельным входом. Это API BatchTextEmbedding, его нельзя заменить запросом input.texts к обычной модели. Он появляется только при публикации подходящего асинхронного тарифа.

curl https://neuroapi.host/alibaba/api/v1/services/embeddings/text-embedding/text-embedding \
  -H "Authorization: Bearer $NEUROAPI_KEY" \
  -H 'Content-Type: application/json' \
  -H 'X-DashScope-Async: enable' \
  -H "Idempotency-Key: $NEUROAPI_IDEMPOTENCY_KEY" \
  -d '{
    "model": "text-embedding-async-v2",
    "input": {"url": "https://example.com/input.txt"},
    "parameters": {"text_type": "document"}
  }'

Пределы: файл до 200 МиБ, до 100000 строк, до 2048 токенов в непустой строке, векторы размерности 1536. Пустые строки пропускаются при вычислении; номера строк нужны для сопоставления с исходным файлом. Параметр text_type принимает document или query; dimension, потоковые параметры и генеративные поля здесь не применяются.

Опрос сохранённого task_id возвращает PENDING, RUNNING, SUCCEEDED, FAILED либо CANCELED. Готовый output.url ведёт к закрытому архиву .jsonl.gz: распакуйте gzip и читайте JSON отдельно по строкам. NeuroAPI проверяет формат, конечные векторы и индексы, сохраняет результат на 24 часа и выдаёт новую временную ссылку при опросе. После хранения ссылки исчезают, состояние результата становится UNKNOWN; повторной генерации и списания нет.

Во время ожидания резервируется верхняя граница по непустым строкам. Итоговая стоимость определяется только подтверждённым usage.total_tokens и зафиксированной ценой этой модели. Этот асинхронный продукт не получает автоматическую скидку или коэффициент 0,5 из другого Batch API. Обычный /v1/batches имеет отдельную поддержку моделей и отдельные цены.

Список задач и отмена

GET /alibaba/api/v1/tasks объединяет файловое ASR, файловые эмбеддинги, нативные изображения и совместимые видеозадачи своего рабочего пространства. Ключ должен по-прежнему иметь доступ к модели; изображения и видео видит создавший их пользователь в исходном рабочем пространстве. Поддерживаются page_no, page_size, task_id, model_name, status, start_time и end_time; даты задаются в формате YYYYMMDDhhmmss, YYYY-MM-DD HH:mm:ss или RFC 3339, диапазон — до 24 часов. Для последовательного чтения можно передать after из next_after; total при этом относится ко всему набору по фильтрам. Фильтры api_key_id и region не открывают ресурсы внешнего аккаунта.

POST /alibaba/api/v1/tasks/{id}/cancel принимает запрос отмены файлового ASR, файловых эмбеддингов, асинхронных изображений и видео до запуска либо в состоянии PENDING. Ответ 200 содержит JSON-строку с идентификатором запроса, например "req_cancel_…". Это подтверждение запроса, а итоговое состояние проверяйте через GET /alibaba/api/v1/tasks/{id}.

Между запросом отмены и его обработкой задача может начать выполняться или успешно завершиться. Поэтому подтверждение отмены, таймаут и обрыв соединения сами по себе не возвращают средства. Если задача завершилась успешно, результат остаётся доступен и оплачивается по обычным правилам. При подтверждённом CANCELED удержание возвращается.

Новый запрос отмены уже выполняющейся или завершённой задачи возвращает 400 с кодом native_task_cancel_unsupported; недоступный вашему ключу идентификатор — 404. Повтор принятого запроса не создаёт новую задачу и не отправляет дополнительную команду отмены. Если результат выполнения ещё выясняется, проверяйте исходную задачу: повторно создавать платное задание для проверки состояния не нужно.

Для изображений, у которых генерация выполняется одним синхронным запросом, отмена доступна только до начала генерации. После запуска такая задача продолжает обработку, даже если соединение с клиентом прервалось. Используйте исходный идентификатор из ответа NeuroAPI: после перезапуска сервис продолжает опрос принятой задачи или сохранение уже полученного результата без повторного платного запуска генерации. Если ответ потерян и идентификатор выполнения или готовый результат не были сохранены, состояние остаётся UNKNOWN, а резерв удерживается до выяснения результата. Старые задачи без подтверждённого состояния выполнения могут быть недоступны для отмены; их результат проверяется обычным GET.

WebSocket: realtime и inference

Нативный realtime Omni — самостоятельный протокол, отличный от HTTP-фасада Omni выше. Реализованы точный qwen3.8-omni-flash-realtime, версии qwen3.5-omni-plus-realtime / qwen3.5-omni-flash-realtime и их снимки 2026-03-15. Для доступа всё равно требуются опубликованные возможности конкретной модели и тарифа.

Текущий аудиоконтур Omni принимает квалифицированный PCM/s16le; написание pcm16 старого SDK обозначает тот же PCM. Это не обещает G.711, Opus или MP3. У 3.8 вход 16 кГц, выход 24 кГц mono, а многоканальный вход имеет отдельные профили на 1/2/4 канала. У 3.5 действует собственный mono-профиль частот. JPEG-кадры ограничены 256 КиБ Base64, стороной до 1920 пикселей и площадью не более 1920×1080 пикселей. Другие видеокодеки из этого не следуют.

Резерв для realtime Omni учитывает физический предел 196608 входных и 65536 выходных токенов. Маленький max_tokens ограничивает возвращаемый ответ, но не доказывает меньший объём вычислений и не уменьшает этот резерв. VAD не запускает неоплаченную генерацию: автоматическое create_response отключается, подтверждение настроек проверяется до приёма аудио, а каждый response.create получает собственный проверенный бюджет. Встроенный поиск, MCP и дополнительная транскрипция в realtime Omni пока отклоняются: разрешение на managed-поиск обычной текстовой модели сюда не переносится.

Используйте адрес, опубликованный для конкретной модели:

wss://neuroapi.host/alibaba/api-ws/v1/realtime
wss://neuroapi.host/alibaba/api-ws/v1/inference

Авторизация остаётся в заголовке Authorization: Bearer $NEUROAPI_KEY. Не переносите секрет в query string. realtime использует событийный протокол сообщений соответствующего семейства, например session.update, input_audio_buffer.append и response.*. inference использует run-task / continue-task / finish-task, task-started, двоичные аудиофреймы и task-finished. Для Sambert текст передаётся целиком с run-task: duplex-последовательность других семейств к нему не подходит.

Qwen realtime TTS, подходящие версии CosyVoice/Sambert и realtime ASR имеют свои допустимые параметры, голоса, форматы и частоты дискретизации. На каждом новом задании проверяются ключ, модель, текущий тариф и конечный бюджет. Наличие HTTP TTS не гарантирует WebSocket и наоборот. Используйте опубликованный путь, а не случайную замену /realtime на /inference.

Например, после подключения к /inference отправьте нативный запуск опубликованной модели CosyVoice:

{
  "header": {"action": "run-task", "task_id": "client-task-001", "streaming": "duplex"},
  "payload": {
    "task_group": "audio",
    "task": "tts",
    "function": "SpeechSynthesizer",
    "model": "cosyvoice-v3-plus",
    "parameters": {"voice": "longxiaochun", "format": "pcm", "sample_rate": 24000},
    "input": {}
  }
}

Дождитесь task-started. Затем передайте текст, сохраняя тот же task_id:

{
  "header": {"action": "continue-task", "task_id": "client-task-001", "streaming": "duplex"},
  "payload": {"input": {"text": "Здравствуйте!"}}
}

Завершите вход сообщением finish-task с тем же заголовком и payload: {"input": {}}. Читайте двоичные аудиофрагменты до task-finished; PCM не является WAV-файлом с готовым заголовком. В ASR последовательность аналогична, но после task-started отправляются двоичные аудиоданные, а результат читается из событий распознавания. Не меняйте голос или модель произвольно внутри принятого задания.

Для inference ASR семейств Fun, Paraformer и Qwen Audio 3.0 Streaming поддерживается также format: "wav": один законченный RIFF/WAVE-файл с PCM16 mono и частотой из sample_rate. Передавайте исходные байты файла, включая заголовок, последовательными двоичными фрагментами; отдельный WAV на каждый фрагмент не нужен. Длительность считается только по аудиосэмплам, без заголовка и метаданных. Повреждённый или незавершённый файл отклоняется. Этот режим не распространяется на Qwen3 ASR /realtime и Omni realtime.

После отключения нет обещания возобновить ту же сессию. Сначала выясните состояние и расход исходного задания; автоматическая перепосылка старого аудио или текста создаёт новое платное выполнение. Сохранённые данные расхода используются для завершения учёта; WebSocket-соединение и аудиосессия не восстанавливаются автоматически. Неподтверждённые токенные бюджеты Qwen Audio 3.1 Flash/Next не выдаются за работающую поддержку.

Отдельный HTTP TTS

Для соответствующего опубликованного профиля Qwen Audio используйте /alibaba/api/v1/services/audio/tts/SpeechSynthesizer с input.text и совместимым input.voice. Поддержка SSML объявляется моделью отдельно: enable_ssml разрешает только ограниченный набор разметки, без внешних файлов, DTD и переключения голоса. Теги не считаются произнесённым текстом; стоимость символов определяется правилами модели, а не размером XML-файла. Синтез с токенной оплатой и генерация аудио имеют другой бюджет и не разрешаются одним лишь наличием этого URL.

Собственные голоса

Сначала проверьте, опубликована ли кастомизация для выбранной модели. Все операции используют POST /alibaba/api/v1/services/audio/tts/customization. Современный model: "voice-enrollment" принимает действия create_voice, list_voice, query_voice, update_voice, delete_voice; у прежних интерфейсов имена действий могут быть create, list, query, delete.

При создании укажите публичный target_model и подходящий аудиопример либо описание голоса. Аудио сохраняется перед выполнением; поддерживаются публичный HTTPS, допустимый Data URI и собственная временная SDK-загрузка. Предел NeuroAPI — 16 МиБ, проверяемая длительность 3–30 секунд у нового формата и 5–30 секунд у legacy-клонирования. Форматы — WAV, MP3 и Ogg. Это проверяемые ограничения сервиса, а не обещание любого режима модели.

Сохраняйте выданный ID вида nv_... и используйте его в синтезе и запросах query/update/delete. Голос принадлежит своему рабочему пространству и связан с целевой моделью: его нельзя использовать для произвольного другого синтеза. Статус DEPLOYING означает подготовку; дождитесь пригодного состояния. Сам голос является постоянным ресурсом, а не файлом SDK на 48 часов. Предпросмотр хранится закрыто 24 часа и возвращается по временной ссылке.

Создание в поддерживаемом новом voice-enrollment сейчас имеет нулевую плату за саму кастомизацию; последующий синтез оплачивается отдельно. Legacy-клонирование через qwen-voice-enrollment имеет базовую стоимость 0,01 USD за создание, умноженную на наценку физического тарифа NeuroAPI; корпоративная процентная скидка применяется один раз. Итог в рублях зависит от действующего курса. Базовая ставка указана в международной карточке qwen-voice-enrollment; её нельзя подменять ставкой в CNY из другого договора. Для платного legacy-дизайна без подтверждённой цены создание недоступно. Просмотр списка, проверка и удаление не становятся платными только потому, что в ответе присутствует usage.count: 1.

На мутациях используйте сохранённый Idempotency-Key; изменение тела под тем же ключом вернёт конфликт. При неопределённом результате создания не запускайте его ещё раз с новым ключом. Готовый голос не следует удалять, пока он используется выполняющимся синтезом.

Локальные файлы в DashScope SDK

Для мультимодальных запросов SDK может сам загрузить локальный файл перед генерацией. Вызов использует тот же базовый URL и ваш ключ NeuroAPI:

import os
from pathlib import Path
import dashscope

dashscope.base_http_api_url = "https://neuroapi.host/alibaba/api/v1"
image = Path("input.png").resolve().as_uri()
response = dashscope.MultiModalConversation.call(
    api_key=os.environ["NEUROAPI_KEY"],
    model="qwen3.7-plus",
    messages=[{"role": "user", "content": [
        {"image": image}, {"text": "Опиши изображение."}
    ]}],
    enable_thinking=False,
    max_tokens=128,
)
if response.status_code != 200:
    raise RuntimeError(response.code, response.message)
print(response.output)

SDK получает разрешение через GET /alibaba/api/v1/uploads?action=getPolicy&model=..., загружает файл подписанной формой на адрес из ответа и использует временную ссылку oss://neuroapi/.... Разрешение на загрузку действует 10 минут, сам закрытый файл — 48 часов. Пределы: 16 МиБ на файл, до 512 файлов и 1 ГиБ в сумме на владельца. Лимиты конкретной модели могут быть строже: например, у LLM и Omni суммарный декодированный медиавход ограничен 16 МиБ, а у ASR действует предел Base64 выше.

Такая ссылка привязана к ключу, владельцу и конкретной модели. Её нельзя передать другому аккаунту, ключу или произвольной модели. При ручном использовании временной ссылки добавьте X-DashScope-OssResourceResolve: enable; SDK делает это сам. Не подставляйте произвольный внешний oss:// вместо ссылки NeuroAPI. За один запрос временные SDK-ссылки подставляются не более чем на 16 МиБ декодированного содержимого, даже если выбранная операция допускает больше при прямой передаче публичных HTTPS-ссылок.

Отдельная поверхность /alibaba/api/v1/files позволяет загружать, перечислять, читать метаданные и удалять закрытые файлы. Загрузка — multipart POST с полями purpose=inference либо file-extract и files; список — GET с page и page_size, один ресурс — GET/DELETE /files/{file_id}. Управляющий file_id не равен временной ссылке SDK и не обещает автоматический разбор документа. Файлы для fine-tuning и Batch относятся к другим жизненным циклам и здесь не принимаются.

Оплата, кэш и ограничения

Цена определяется карточкой модели и выбранным тарифом NeuroAPI. Наценка тарифа уже учтена в опубликованной цене. Не умножайте её повторно.

У генерации текста учитываются вход, выход и применимые модельные правила. У эмбеддингов и ранжирования нет платы за генеративный выход и отдельной ставки кэша LLM. Для мультимодальных эмбеддингов ставки текстового и графического входа могут различаться: карточка показывает их отдельно. Сами векторы и оценки не следует оценивать как выходные токены чат-модели.

usage зависит от задачи: текстовые эмбеддинги и ранжирование используют total_tokens, мультимодальные ответы могут дополнительно содержать input_tokens, input_tokens_details, image_tokens, output_tokens. Не складывайте детализацию повторно с её общим счётчиком. Окончательное списание смотрите в истории операций NeuroAPI.

Для LLM неявный префиксный кэш может сработать автоматически, если модель поддерживает его. Попадание не гарантируется каждым повтором: одинаковый стабильный префикс полезен, но изменение сообщений может изменить результат. Явные cache-маркеры допускаются только в поддерживаемой комбинации модели и настроек; они не являются универсальным способом получить скидку.

Общий JSON-запрос Native ограничен 32 МиБ. Для изображений и кадров LLM, Omni и мультимодальных эмбеддингов действует дополнительный суммарный предел 16 МиБ после декодирования; у генерации изображений — собственные пределы модели. Лимиты контекста, ответа, числа элементов и медиа действуют дополнительно. Неверные поля не отбрасываются молча. Hosted tools, сессии, background и расширения, не описанные для конкретной операции, не следует отправлять «на пробу».

Ошибки и безопасные повторы

Нативная ошибка имеет собственную форму, а не OpenAI error:

{
  "code": "invalid_text_request",
  "message": "Проверьте формат и параметры запроса.",
  "request_id": "request-example"
}

Неподдерживаемая комбинация отклоняется до обработки. Обрыв клиента после принятого запроса не доказывает отсутствие выполнения. Не включайте общий автоматический retry для всех сетевых исключений.

В SDK 2 сохраняйте max_retries=0, как в примере клиента выше. В старых ветках SDK могут быть собственные транспортные повторы, не управляемые одноимённым параметром генерации. Не добавляйте max_retries внутрь parameters: это не параметр модели. Для создания фоновых операций и голосов передавайте один сохранённый Idempotency-Key на всё время повторов той же операции. Повтор с новым ключом означает новую работу. Обычные синхронные генерации и изображения не получают идемпотентность автоматически от заголовка.

Для HTTP-клиента без автоматического повтора создания:

import os
import uuid
import requests
from requests.adapters import HTTPAdapter

# Сохраните это значение вместе с заданием до первого POST.
operation_key = str(uuid.uuid4())
session = requests.Session()
session.mount("https://", HTTPAdapter(max_retries=0))
response = session.post(
    "https://neuroapi.host/alibaba/api/v1/services/embeddings/text-embedding/text-embedding",
    headers={
        "Authorization": f"Bearer {os.environ['NEUROAPI_KEY']}",
        "X-DashScope-Async": "enable",
        "Idempotency-Key": operation_key,
    },
    json={"model": "text-embedding-async-v2", "input": {"url": "https://example.com/input.txt"}},
    timeout=(10, 600),
)
response.raise_for_status()
task_id = response.json()["output"]["task_id"]
print(task_id)  # Далее опрашивайте GET /alibaba/api/v1/tasks/{task_id}.

Если POST завершился неопределённо, используйте сохранённый ключ и исходное тело для выяснения той же фоновой операции. Не генерируйте новый UUID при каждом сетевом исключении.

Встроенный поиск, код и документы

У обычной Native-генерации предусмотрены enable_search, search_options и enable_code_interpreter, но выполнение включается только для отдельно настроенной и опубликованной модели. Если исполнитель или фиксированная стоимость не определены, запрос отклоняется до резервирования средств. Наличие поля в SDK не означает бесплатный поиск или выполнение кода.

Оплачиваются подтверждённые сервисные операции поиска/кода и токены промежуточных модельных шагов. Число операций и модельных шагов ограничивает NeuroAPI; max_tool_calls клиента не снимает эти границы. Поддерживаемые источники и цитаты возвращаются отдельно от обычных функций приложения. Часть расширенных search_options может быть отклонена до выполнения. Плагины X-DashScope-Plugin требуют отдельной опубликованной схемы.

Обычные Generation и MultiModalConversation не являются API управления сессиями, background-заданиями или аккаунтом. /files не даёт доступ к чужому OSS, настройкам рабочего пространства или обучению модели. Обработка документов и ссылки fileid:// доступны только в отдельно разрешённом документном контуре с проверкой владельца и текущего доступа к модели.

Источники и следующие шаги

NeuroAPI поддерживает описанное выше подмножество. Возможность в документации SDK сама по себе не означает её доступность через NeuroAPI.

• DashScope: генерация текста и мультимодальные запросы
• Текстовые эмбеддинги
• Файловые эмбеддинги BatchTextEmbedding
• Мультимодальные эмбеддинги
• Ранжирование текста
• Перевод Qwen-MT
• Изображения Qwen
• Omni
• Распознавание речи
• Файловое распознавание Paraformer
• Создание собственных голосов
• WebSocket-протоколы
• Синтез речи
• Временные загрузки SDK
• Авторизация NeuroAPI · Лимиты · Ошибки · Эмбеддинги и поиск