Skip to main content
API7.ai Logo

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"

Create a complete declarative resources file for this provider:

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:

# The local quickstarts use http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

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. AISIX detects chat, completions, and Responses envelopes and records supported usage fields. Requests without a recognized carrier field remain opaque: buffered responses record zero tokens, while opaque SSE can still record top-level supported usage fields. 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: