Skip to main content
API7.ai Logo
Version: Dev

Novita AI

Novita AI provides hosted inference for a catalog of language models. Applications select those models through stable AISIX aliases and authenticate with gateway-issued caller keys.

Prerequisites​

Before starting, prepare the following:

  • One AISIX setup:
    • For AISIX Cloud, an environment with an attached gateway and a write-scoped admin token. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7.
    • For the open-source AISIX gateway, prepare either a local AISIX installation or the Docker setup from the Open-Source AISIX Gateway Quickstart. Configure the gateway to load a declarative resources file.
  • A Novita AI API key.
  • curl and jq.

Configure with AISIX Cloud​

Export the AISIX Cloud connection details:

# AISIX_CP is the Admin API base URL; include /api and omit a trailing slash
# The local On-Premises quickstart uses http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

Novita AI is a community catalog provider with an OpenAI-compatible API. AISIX connects through the openai adapter and authenticates upstream requests with a bearer token.

Create a Provider Key​

export NOVITA_API_KEY="YOUR_NOVITA_API_KEY"

PROVIDER_KEY_ID=$(
  curl -sS -X POST "$AISIX_CP/provider_keys" \
    -H "Authorization: Bearer $AISIX_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "display_name": "novita-prod",
      "provider": "novita-ai",
      "api_key": "'"${NOVITA_API_KEY}"'",
      "api_base": "https://api.novita.ai/openai/v1",
      "allowed_environments": ["'"${ENV_ID}"'"]
    }' | jq -er '.provider_key.id'
)

echo "$PROVIDER_KEY_ID"

The provider ID includes the -ai suffix. novita is not the AISIX catalog ID.

The API base must include /openai. This guide uses Novita's documented /openai/v1 root, so AISIX appends /chat/completions to produce https://api.novita.ai/openai/v1/chat/completions. Novita also accepts /openai without the version segment, which is the current synchronized catalog value. Using the bare host would send traffic to a route Novita does not document for LLM inference.

AISIX derives the openai adapter for this catalog provider. Omit adapter from the request.

Create a Model​

Create an alias with Novita's publisher-namespaced model ID:

MODEL_ID=$(
  curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
    -H "Authorization: Bearer $AISIX_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "display_name": "novita-deepseek-prod",
      "model_name": "deepseek/deepseek-v3.2",
      "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
    }' | jq -er '.model.id'
)

echo "$MODEL_ID"

Model IDs and availability change as the catalog from Novita is updated. Copy the current ID, including its publisher prefix and casing, from the Novita model list.

Create a Caller API Key​

AISIX_API_KEY=$(
  curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
    -H "Authorization: Bearer $AISIX_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "display_name": "novita-caller",
      "allowed_models": ["'"${MODEL_ID}"'"]
    }' | jq -er '.plaintext'
)

echo "$AISIX_API_KEY"

Configure with the Open-Source AISIX Gateway​

Export the upstream credential and choose the caller API key that applications will send to the gateway:

export NOVITA_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

For a new gateway, use this complete resources file. For an existing gateway, merge the entries into its current file, preserving its other resources:

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: "novita-prod"
    provider: "novita-ai"
    adapter: "openai"
    api_key: ${NOVITA_API_KEY}
    api_base: "https://api.novita.ai/openai/v1"

models:
  - display_name: "novita-deepseek-prod"
    provider: "novita-ai"
    model_name: "deepseek/deepseek-v3.2"
    provider_key: "novita-prod"

api_keys:
  - display_name: "novita-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "novita-deepseek-prod"

If AISIX is installed locally, validate the file before loading it:

aisix validate --resources resources.yaml

After validation, start the gateway with the referenced environment variables in its process environment. Reload an existing gateway only if those variables are already available to the process; otherwise, restart it with the updated environment.

If you use Docker, adapt the validation and startup commands in the Open-Source AISIX Gateway Quickstart. Mount this resources.yaml file and pass every environment variable it references with -e in both commands. After the resources load, prepare the shared verification request below:

export AISIX_API_KEY="$CALLER_API_KEY"

Verify the Provider Connection​

Export the AISIX gateway origin:

# AISIX_PROXY has no trailing slash or endpoint path
# The local quickstarts use http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

Send a chat-completions request through the AISIX proxy:

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer $AISIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "novita-deepseek-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Novita AI."
      }
    ]
  }'

AISIX forwards deepseek/deepseek-v3.2 to the Novita OpenAI-compatible chat endpoint with the Novita API key.

Review Model Capabilities​

The deepseek/deepseek-v3.2 model in this guide is current, text-only, and supports reasoning, function tools, and structured output. Novita's chat API also supports model-specific image, video, and audio input, text or audio output, and controls such as enable_thinking and separate_reasoning. AISIX forwards typed content blocks, tools, structured-output configuration, and unknown top-level request fields to the OpenAI-compatible upstream.

AISIX normalizes Novita's reasoning_content field on chat responses. It does not preserve the optional reasoning_details array that some Novita models require for interleaved thinking across tool calls. Use a passthrough route for those models and replay the complete native assistant message. Novita also accepts n greater than 1, but AISIX returns only the first choice on normalized chat routes.

Endpoint Coverage​

RouteBehavior with a Novita alias
/v1/chat/completionsSupported, including streaming, tools, structured output, reasoning, and multimodal content supported by the selected model.
/v1/completionsSupported through the openai adapter for a compatible Novita model.
/v1/responsesSupported through the Responses bridge, which translates to chat completions. Novita does not publish a native Responses route on this API root. Fields without a chat equivalent are ignored, and Novita reasoning is not preserved in the returned Responses output.
/v1/messagesSupported through Anthropic-to-chat translation against the OpenAI-compatible root. The bridge does not preserve Novita reasoning as Anthropic thinking blocks. /v1/messages/count_tokens requires an Anthropic-backed model and rejects this configuration.
/v1/embeddingsSupported with a separate alias for a Novita embedding model served on this root.
/v1/files and /v1/batchesSupported through the openai adapter. AISIX rewrites returned file and batch IDs so normalized follow-up calls route to the same alias. Each request in an uploaded batch JSONL file must use the upstream Novita model ID; AISIX does not rewrite file contents, and Novita requires one model per batch file.
/v1/fine_tuning/jobs and /v1/audio/*Not supported. Novita does not publish compatible routes beneath the configured OpenAI root. Audio input or output through compatible chat models is a separate capability.
/v1/images/generationsRejected with 400 because the normalized route requires provider: openai. Novita's image-generation APIs use separate host-root paths outside the configured API base.
/v1/rerankRejected with 400 because the normalized route does not accept novita-ai. Novita's native /openai/v1/rerank route is reachable through a passthrough route.
/v1/videosRejected with 501 not_implemented because the normalized route does not support novita-ai. Novita's video-generation APIs use separate host-root paths outside the configured API base; video input to a compatible chat model is a separate capability.
/passthrough/novita-ai/*Available through a configured passthrough route for Novita-native routes beneath the route's target_url, including /rerank and /models.

File and batch management calls record zero tokens. When a normalized batch retrieval first observes a completed job, AISIX downloads the output file and attributes its aggregate token usage and calculated cost to the routing alias.

Novita also publishes an Anthropic-compatible API at https://api.novita.ai/anthropic. That sibling root is outside the /openai/v1 root used in this guide, so a passthrough route targeting the OpenAI-compatible root cannot reach it. Native Anthropic use requires a separate passthrough route with that root as its target_url, granted on the caller key's allowed_routes.

A passthrough route stays beneath its target_url, so a route targeting the /openai/v1 root cannot reach Novita's host-root /v3 image, video, or audio APIs. For reachable paths, it does not rewrite an AISIX model alias or resource ID. For the request shapes that record token usage, see Envelope Detection and Usage. AISIX relays provider responses and SSE incrementally rather than buffering them.

The /passthrough/novita-ai paths on this page assume a passthrough route claiming that prefix with https://api.novita.ai/openai/v1 as its target_url and the Novita provider key for credential injection; grant the route name on the caller key's allowed_routes. A route binds one target and credential, so use separate routes for different Novita accounts or roots.

Troubleshooting​

SymptomCheck
Upstream authentication errorConfirm NOVITA_API_KEY is active.
Upstream 404Keep /openai in api_base, and verify that the requested route exists beneath that root.
Model not foundCopy the complete publisher-namespaced model ID from Novita.
Provider key creation returns 400Use provider: "novita-ai" and omit adapter.

Next Steps​

You have now connected AISIX to Novita AI and verified the model alias. Continue with these guides: