OpenAI-совместимый API

NexusAPI предоставляет drop-in замену для OpenAI SDK по адресу /v1/*. Стандартный openai пакет (Python и Node) работает без правок в коде — только base_url.

from openai import OpenAI

client = OpenAI(
    base_url="https://nexusapi.dev/v1",
    api_key="ВАШ_NEXUS_КЛЮЧ",  # обычный ключ NexusAPI, не sk-...
)

Точно так же работают LangChain, LlamaIndex, Vercel AI SDK, Continue, Cline и другие инструменты, которые принимают base_url и api_key.

Что поддерживается

OpenAI endpoint	NexusAPI поведение
GET /v1/models	Возвращает каталог моделей в OpenAI-shape
POST /v1/chat/completions	Текстовые модели в OpenAI-формате; поддерживает streaming и tools
POST /v1/images/generations	Sync — ждёт завершения задачи до 180с, возвращает URL
POST /v1/videos	Async (Sora-style) — возвращает video.id сразу
GET /v1/videos/{id}	Опрос статуса задачи, URL когда status=completed

Что не поддерживается (пока)

• POST /v1/embeddings — у нас нет embedding-моделей
• POST /v1/images/edits — image-to-image через нативный POST /generate
• n > 1 в images.generate — пока только одна картинка за запрос
• response_format=b64_json — пока только url
• POST /v1/audio/* — у нас нет audio-моделей

Текстовые модели

Используй стандартный OpenAI Chat Completions API. Все активные Claude и GPT модели перечислены на странице Текстовые модели; актуальный список также возвращает GET /v1/models с API-ключом.

from openai import OpenAI

client = OpenAI(base_url="https://nexusapi.dev/v1", api_key="ВАШ_NEXUS_КЛЮЧ")

response = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Коротко объясни задачу."}],
    max_tokens=1000,
)
print(response.choices[0].message.content)

Для SSE добавь stream=True. Параметры tools и tool_choice передаются в OpenAI-совместимом формате. Стоимость LLM указана в рублях за 1 млн токенов и рассчитывается по фактическому usage.

Генерация изображения (sync)

Python (openai)

from openai import OpenAI

client = OpenAI(
    base_url="https://nexusapi.dev/v1",
    api_key="ВАШ_NEXUS_КЛЮЧ",
)

resp = client.images.generate(
    model="nano-banana",
    prompt="Минималистичный логотип кофейни, чёрно-белый",
    size="1024x1024",
)
print(resp.data[0].url)

Node.js (openai)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://nexusapi.dev/v1",
  apiKey: process.env.NEXUS_KEY,
});

const resp = await client.images.generate({
  model: "nano-banana",
  prompt: "Минималистичный логотип кофейни",
  size: "1024x1024",
});
console.log(resp.data[0].url);

curl

curl -X POST https://nexusapi.dev/v1/images/generations \
  -H "Authorization: Bearer $NEXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana",
    "prompt": "Минималистичный логотип кофейни",
    "size": "1024x1024"
  }'

Response:

{
  "created": 1733000000,
  "data": [
    { "url": "https://nexusapi-s3.../result.png" }
  ]
}

Маппинг size → aspect_ratio

1024x1024 → 1:1, 1024x1792 → 9:16, 1792x1024 → 16:9, 1024x768 → 4:3. Нестандартные размеры берут ближайшее по площадному соотношению.

Таймаут 180 секунд

Sync-эндпоинт ждёт завершения задачи до 3 минут, после — 504. Для быстрых моделей (nano-banana 10-30с, sora-image 30-60с) этого с запасом. Для потенциально долгих задач используйте POST /v1/videos (async) или нативный POST /generate.

Генерация видео (async, Sora-style)

Python (openai)

from openai import OpenAI
import time

client = OpenAI(base_url="https://nexusapi.dev/v1", api_key="...")

video = client.videos.create(
    model="veo-3-fast",
    prompt="Кот играет на пианино в джаз-баре",
    size="1920x1080",
    seconds=8,
)

while video.status not in ("completed", "failed"):
    time.sleep(5)
    video = client.videos.retrieve(video.id)

print(video.url if video.status == "completed" else video.error.message)

curl

# 1. Создать задачу
curl -X POST https://nexusapi.dev/v1/videos \
  -H "Authorization: Bearer $NEXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3-fast",
    "prompt": "Кот играет на пианино в джаз-баре",
    "size": "1920x1080",
    "seconds": 8
  }'

# Ответ: { "id": "550e8400-...", "status": "queued", ... }

# 2. Опросить статус
curl https://nexusapi.dev/v1/videos/550e8400-... \
  -H "Authorization: Bearer $NEXUS_KEY"

Status переходы:

queued → in_progress → completed (url доступен)
                    └→ failed     (error.message заполнен, баланс возвращён)

Соответствие native-статусам

OpenAI-shape использует queued/in_progress (как Sora). В нативном API те же фазы называются pending/processing. Один и тот же task под капотом — отличается только формат ответа эндпоинта. Подробнее — Задачи и статусы.

OpenAI-compat (/v1/*)	Native (/generate, /tasks/{id})
queued	pending
in_progress	processing
completed	completed
failed	failed

При status=completed ответ содержит дополнительное поле url — это URL готового видео в S3. Стандартный OpenAI Sora SDK ожидает download через videos.download_content(id), но эта обвязка для нашего S3 пока не реализована, используй url напрямую.

Параметры моделей

Имена моделей — те же что в нативном API. Полный список — GET /v1/models или каталог моделей.

Image-модели

nano-banana, nano-banana-2-lite, nano-banana-2, nano-banana-pro, nano-banana-pro-vip, gpt-image-2, gpt-image-2-vip, seedream-5.0-lite, seedream-5.0-pro

Video-модели

veo-*, kling-*, seedance-*, gemini-omni-flash-video, gemini-omni-flash-video-edit, minimax-3-hailuo, wan/2-7-text-to-video, wan/2-7-image-to-video

Native-параметры через extra_body

OpenAI-формат покрывает только основные параметры (prompt, size, seconds, seed). Чтобы передать любые native-параметры модели (вебхуки, image-to-video референсы, negative prompts, model-specific настройки), используй стандартный OpenAI SDK-паттерн extra_body:

Python

# Kling motion: image-to-video с обязательным image_url
video = client.videos.create(
    model="kling-v2.6-motion-1080p",
    prompt="camera slowly pulls back",
    seconds=8,
    extra_body={
        "image_url": "https://your-bucket.s3.amazonaws.com/start.jpg",
        "negative_prompt": "low quality, blurry",
        "webhook_url": "https://your-app.com/nexus-callback",
    },
)

# Seedance video-to-video: список reference-видео
video = client.videos.create(
    model="seedance-2.0",
    prompt="continue in the same style",
    seconds=8,
    resolution="1080p",
    extra_body={
        "video_urls": ["https://your-bucket.s3.../ref.mp4"],
    },
)

# Veo extend: удлинить существующее Veo-видео
video = client.videos.create(
    model="veo-extend",
    prompt="camera keeps moving forward",
    seconds=8,
    extra_body={
        "source_video_url": "https://nexusapi-s3.../prior-veo-result.mp4",
    },
)

# Nano-banana image-edit (image-to-image)
img = client.images.generate(
    model="nano-banana-pro",
    prompt="make the sky more dramatic",
    size="1024x1024",
    extra_body={
        "image_url": "https://your-bucket.s3.amazonaws.com/photo.jpg",
    },
)

Node.js

// Кling motion + webhook
const video = await client.videos.create({
  model: "kling-v2.6-motion-1080p",
  prompt: "camera slowly pulls back",
  seconds: 8,
  // Любые лишние поля просто прокидываются в body — SDK не валидирует
  image_url: "https://your-bucket.s3.amazonaws.com/start.jpg",
  negative_prompt: "low quality",
  webhook_url: "https://your-app.com/nexus-callback",
});

curl

# extra-параметры — просто дополнительные JSON-поля
curl -X POST https://nexusapi.dev/v1/videos \
  -H "Authorization: Bearer $NEXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v2.6-motion-1080p",
    "prompt": "camera slowly pulls back",
    "seconds": 8,
    "image_url": "https://your-bucket.s3.amazonaws.com/start.jpg",
    "negative_prompt": "low quality",
    "webhook_url": "https://your-app.com/nexus-callback"
  }'

Куда смотреть какие параметры доступны

Каждая модель имеет свой набор параметров. Они описаны в нативном API Reference и на страницах конкретных моделей в каталоге (см. секции «Параметры запроса»). Все они передаются через extra_body для OpenAI SDK или просто как дополнительные JSON-поля при ручном POST.

Pre-маппинг параметров (явные алиасы)

Для удобства часть OpenAI-полей маппится в наши native-имена автоматически:

OpenAI поле	Native поле	Где
model	model_name	images + videos
prompt	prompt	images + videos
size: "WxH"	aspect_ratio: "16:9"	images + videos (ближайшее по площадному соотношению)
seconds: int	duration: int	videos
input_reference: str	image_url: str	videos (image-to-video)
seed: int	seed: int	images + videos
resolution: str	resolution: str	videos (seedance)

Поля игнорируются (приняты, но не используются — нет смысла у наших моделей): quality, response_format (кроме "url").

Любые не перечисленные выше поля просто прокидываются в native params без изменений — поэтому всё, что описано в нативной доке, работает.

Аутентификация

Тот же Bearer-токен что у нативного /generate. Создаётся в panel.nexusapi.dev → API ключи. Подробнее — Аутентификация.

Ошибки

Возвращаются в формате OpenAI:

{
  "error": {
    "message": "Insufficient funds. Required: 50.0.",
    "type": "billing_error"
  }
}

Типы ошибок (type):

• invalid_request_error — невалидное тело (400, 422)
• authentication_error — нет ключа или невалидный (401)
• billing_error — недостаточно средств (402)
• permission_error — restrictions ключа (403)
• not_found_error — нет такой модели/задачи (404)
• rate_limit_error — rate-limit ключа (429)
• timeout_error — задача не успела за 180s (504)
• service_unavailable — maintenance-режим (503)
• api_error — провал генерации, прочее (500)

Биллинг

OpenAI-эндпоинты используют тот же hold + refund flow, что и нативный /generate. Стоимость списывается при создании задачи, при failed возвращается. Подробнее — Биллинг.