Dify: подключение SpeShu.AI как OpenAI-совместимый провайдер

Dify — платформа для LLM-приложений: приложения-чаты, workflow из блоков, агенты, база знаний и публикация результата через API. На неё указывают, когда нужен готовый сценарий без разработки с нуля: загруженные документы, заданный промпт, выбранная модель и выданный наружу эндпоинт. Подключать SpeShu.AI к Dify имеет смысл, когда генерация идёт через один OpenAI-совместимый ключ с рублёвым балансом, а сама логика — визуальный workflow, который должны дорабатывать люди без навыков разработки.

Два значения определяют всю настройку:

base URL = https://speshu.ai/api/v1 — с суффиксом /v1
API key = значение из раздела API-ключей на speshu.ai/profile

Dify обращается к моделям через OpenAI-совместимые эндпоинты, поэтому отдельный плагин для SpeShu.AI не нужен: подходит штатный провайдер OpenAI-API-compatible, и вся настройка сводится к этим двум полям.

Установка

Для self-hosted: Docker Compose с образом Dify и его зависимостями (PostgreSQL, Redis, Weaviate для базы знаний, sandbox-сервисы). Запуск — по инструкции Dify для вашей платформы; SpeShu.AI ставить не нужно, это внешний API.

docker compose up -d

Проверьте, что веб-интерфейс открылся и вы вошли под учётной записью администратора. Ключ Dify для вызова приложения из кода создаётся отдельно: Publish → API Access вашего приложения.

Настройка провайдера

Путь в интерфейсе одинаков для Dify Cloud и для self-hosted.

Установите провайдер OpenAI-API-compatible

Откройте Settings → Model Provider → Install provider и найдите OpenAI-API-compatible (поставщик — LangGenius). Установите и вернитесь к списку провайдеров.

Возьмите идентификатор модели из каталога

Идентификаторы текстовых моделей зашивать в код нельзя: состав каталога меняется, и зашитый в конфиг идентификатор молча устаревает, а запрос падает с 404 model_not_found. Возьмите актуальный и сохраните в переменную:

cURL

export SPESHU_MODEL=$(curl -s https://speshu.ai/api/v1/models \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  | jq -r '.data[0].id')
echo "$SPESHU_MODEL"

.data[0] — первый элемент, чтобы шаг был запускаемым. Выбирайте модель по context_length, cost_completion и наличию зрения. Формат ответа — в разделе Каталог моделей.

Заполните форму провайдера

В карточке OpenAI-API-compatible нажмите Edit и заполните три поля:

Поле формы	Значение
`API Key`	значение ключа `sk-...` из профиля
`API endpoint URL`	`https://speshu.ai/api/v1`
`Model Name`	`$SPESHU_MODEL` — идентификатор из шага выше

Нажмите Save. Модель появится в выпадающих списках LLM-ноды и сразу станет доступна для тестового вызова из карточки.

В поле API endpoint URL суффикс /v1 обязателен. Dify сам дописывает /chat/completions, поэтому https://speshu.ai/api/v1/v1/chat/completions вернёт 404, а вариант без /v1 уведёт запрос на /api/chat/completions. Хвостовой слэш в конце адреса уберите.

Секреты провайдера хранятся в базе Dify и правятся только через интерфейс — в .env вашего развёртывания их нет. Перед коммитом не переносите значения форм в репозиторий. Model Name — единственное поле, которое при смене каталога нужно обновить вручную: при обновлении подставьте новое значение $SPESHU_MODEL.

SpeShu.AI не отдаёт эндпоинт для эмбеддингов. База знаний Dify требует модель эмбеддингов, и подставить туда текстовую модель нельзя. Два честных варианта:(а) Рекомендуемый. Эмбеддинги считает отдельный провайдер, генерацию — SpeShu.AI. Установите в Dify любой OpenAI-совместимый эмбеддинг-провайдер (тот же плагин, с базой и ключом другого сервиса) и выберите его в настройках датасета:

Поле	Значение
`API endpoint URL`	адрес стороннего сервиса — отдельное конфигурационное значение, не SpeShu.AI
`API Key`	ключ стороннего сервиса
`Model Name`	идентификатор модели эмбеддингов этого сервиса

Плата за эмбеддинги идёт этому сервису, а не в кошелёк SpeShu.AI. Ответы и генерация — в рублях по usage.cost.total_cost.(б) Обойтись без базы знаний: приложение-чат, агент или workflow без узлов Knowledge Retrieval. Эмбеддинги тогда не нужны вовсе.

Первый рабочий пример

Проверьте связку не в интерфейсе, а через API самого Dify: так вы убедитесь, что модель, ключ и base URL сошлись на стороне платформы.

cURL

curl -s https://api.dify.ai/v1/chat-messages \
  -H "Authorization: Bearer $DIFY_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {},
    "query": "Ответь одним предложением: зачем нужен API?",
    "response_mode": "blocking",
    "user": "docs-reader"
  }' | jq -r '.answer'

Python

import os

import requests

# Переменные на стороне Dify, не SpeShu.AI:
#   DIFY_API_BASE — https://api.dify.ai/v1 для Cloud, https://<ваш-хост>/v1 для self-hosted
#   DIFY_APP_KEY  — ключ из Publish → API Access конкретного приложения
base = os.environ.get("DIFY_API_BASE", "https://api.dify.ai/v1")

response = requests.post(
    f"{base}/chat-messages",
    headers={
        "Authorization": f"Bearer {os.environ['DIFY_APP_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "inputs": {},
        "query": "Ответь одним предложением: зачем нужен API?",
        "response_mode": "blocking",
        "user": "docs-reader",
    },
    timeout=120,
)
response.raise_for_status()
print(response.json()["answer"])

DIFY_API_BASE и DIFY_APP_KEY — ваши собственные переменные окружения для Dify, а не настройки SpeShu.AI. Здесь два разных пространства имён: база Dify заканчивается на /v1 и обслуживает приложение, база SpeShu.AI — https://speshu.ai/api/v1 и обслуживает модель.

Workflow, поток, инструменты

Возможность Dify	Что делать	Где подробнее
Потоковый вывод	Ничего. `response_mode: "streaming"` в API приложения читает SSE, который Dify разбирает самостоятельно. Проверяется только то, что ответ вообще приходит.	Потоковая передача
Вызов функций	Узлы Tools в агенте и tool-узлы в workflow уходят в модель как `tools[]`. Отдельная настройка не нужна	Вызов функций
Структурированный вывод	LLM-нода с включённым Structured Output и JSON Schema. Поддерживается не всеми моделями каталога — проверяйте пробным запросом	Структурированный вывод
Изображения на вход	Ссылку из `POST /api/v1/storage/upload` подайте в LLM-ноду как переменную в блоке `image_url`. Не каждая модель принимает зрение	Медиаввод
Генерация изображений и видео	Узлом HTTP Request — медиа-API асинхронный и в протокол LLM-провайдера не входит	Создание задачи

Медиагенерация в workflow

Модели изображений, видео, аудио и музыки живут в отдельном API: запрос создаёт задачу, оплата — сразу при создании, результат приходит по опросу. В Dify это два узла: HTTP Request на создание и HTTP Request на опрос, между ними — цикл или пауза.

{
  "method": "POST",
  "url": "https://speshu.ai/api/v1/async/media/tasks",
  "headers": {
    "Authorization": "Bearer sk-ваш-ключ",
    "Content-Type": "application/json",
    "Idempotency-Key": "{{#env.SPESHU_IDEMPOTENCY_KEY#}}"
  },
  "body": {
    "mode": "json",
    "json": {
      "model": "nano-banana-2",
      "input": { "prompt": "{{#start.query#}}" }
    }
  }
}

Опрос состояния — GET https://speshu.ai/api/v1/async/media/tasks/{task_id}, поле статуса — data.state, ссылка на результат — в data.resultJson. Идентификаторы медиа-моделей стабильны, но каталог всё равно стоит сверять через GET /api/v1/media/models.

Деньги списываются при создании задачи, а не при успешном результате. Не переотправляйте создание вслепую: повтор с тем же Idempotency-Key вернёт исходную задачу, с новым — создаст новую и спишет снова. Один ключ на одну логическую операцию — переиспользуйте его во всех повторах.

Что дальше

Начало работы

Разбор первых запросов к API

Потоковая передача

Разбор SSE и кадра со списанием

Вызов функций

Полный цикл вызова инструмента

Создание медиа-задачи

Входные параметры и опрос статуса

Типичные проблемы

Модель не появилась в списке либо 404 model_not_found

Проверьте Model Name в карточке провайдера: значение должно совпадать с элементом id из GET /api/v1/models, без префикса и без кавычек. Затем убедитесь, что адрес — ровно https://speshu.ai/api/v1. Если каталог обновился, возьмите новый идентификатор и впишите его заново.

401 invalid_api_key при тестовом вызове из карточки провайдера

В поле API Key попал ключ от другого сервиса либо значение обрезалось при копировании. Проверьте, что там полная строка с префиксом sk- и без переноса строки, и что ключ не отозван в профиле. Заодно проверьте ключ напрямую: curl -s https://speshu.ai/api/v1/balance -H "Authorization: Bearer $SPESHU_API_KEY".

404 на стриминге, хотя обычный запрос проходит

Проверьте адрес ещё раз. С хвостовым слэшем или с двойным /v1 Dify соберёт неверный путь и получит 404 именно на потоковом маршруте — блокирующий вызов при этом может вести себя иначе из-за кэша модели в интерфейсе.

База знаний не создаётся: нет модели эмбеддингов

Это ожидаемо: сервис не отдаёт эмбеддинги. Подключите сторонний эмбеддинг-провайдер в Dify и выберите его в настройках датасета либо уберите узлы Knowledge Retrieval из сценария.

402 insufficient_quota на первом же запросе

На балансе нет положительной суммы. Пополнение — в веб-приложении на speshu.ai/profile. Баланс проверяют до обращения к модели. За отказ деньги не списываются.

Всё остальное

Полная таблица кодов, три формата ошибок и цикл повторов — на странице Ошибки. Таймауты и квоты — в разделе Лимиты, списания — в разделе Биллинг.

Начало работы

Возможности моделей

Генерация медиа

Фреймворки

Базы данных

Агенты и редакторы

No-code и автоматизация

Dify: подключение SpeShu.AI как OpenAI-совместимый провайдер

Установка

Настройка провайдера

Первый рабочий пример

Workflow, поток, инструменты

Медиагенерация в workflow

Что дальше

Начало работы

Потоковая передача

Вызов функций

Создание медиа-задачи

Типичные проблемы

​Установка

​Настройка провайдера

​Первый рабочий пример

​Workflow, поток, инструменты

​Медиагенерация в workflow

​Что дальше

Начало работы

Потоковая передача

Вызов функций

Создание медиа-задачи

​Типичные проблемы

Установка

Настройка провайдера

Первый рабочий пример

Workflow, поток, инструменты

Медиагенерация в workflow

Что дальше

Типичные проблемы