Amazon Nova API

Amazon Nova is Amazon's family of foundation models, available through a direct API as well as Amazon Bedrock. This guide connects the direct API to AISIX so applications can call Nova through the gateway's OpenAI-compatible API.

This setup is for the API-key-based endpoint at api.nova.amazon.com. It is different from Amazon Bedrock, which uses AWS credentials, a region, and SigV4 request signing. To call Nova through Bedrock, use Amazon Bedrock instead.

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.
An API key issued for the direct Amazon Nova API.
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"

Create a Provider Key

Export the Nova API key:

export NOVA_API_KEY="YOUR_NOVA_API_KEY"

Create the provider 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": "nova-prod",
      "provider": "nova",
      "api_key": "'"${NOVA_API_KEY}"'",
      "api_base": "https://api.nova.amazon.com/v1",
      "allowed_environments": ["'"${ENV_ID}"'"]
    }' | jq -er '.provider_key.id'
)

echo "$PROVIDER_KEY_ID"

AISIX accepts nova through the community catalog and derives the openai adapter with bearer authentication. Do not send adapter on this catalog provider key.

AISIX appends /chat/completions to the configured API base. Keep /v1 in the value; a bare https://api.nova.amazon.com host points at the wrong route.

Create a Model

Create an alias for Nova 2 Lite:

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": "nova-lite-prod",
      "model_name": "nova-2-lite-v1",
      "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
    }' | jq -er '.model.id'
)

echo "$MODEL_ID"

Use the exact model ID published in the Amazon Nova developer documentation. The direct Nova API and Bedrock can use different identifiers for access to the same model family, so do not copy a Bedrock model or inference-profile ARN into this field.

Create a Caller API Key

Create a caller key limited to the Nova alias:

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": "nova-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 NOVA_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: "nova-prod"
    provider: "nova"
    adapter: "openai"
    api_key: ${NOVA_API_KEY}
    api_base: "https://api.nova.amazon.com/v1"

models:
  - display_name: "nova-lite-prod"
    provider: "nova"
    model_name: "nova-2-lite-v1"
    provider_key: "nova-prod"

api_keys:
  - display_name: "nova-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "nova-lite-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": "nova-lite-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Amazon Nova."
      }
    ]
  }'

AISIX sends nova-2-lite-v1 to https://api.nova.amazon.com/v1/chat/completions with the Nova API key in the bearer header.

Choose Between the Nova API and Bedrock

Account path	AISIX provider	Credential and adapter
Direct Nova API	`nova`	Nova API key with the `openai` adapter
Amazon Bedrock	`amazon-bedrock`	AWS access credentials with the `bedrock` adapter

Keep the two paths in separate provider keys. This makes credential rotation, account attribution, and failover behavior explicit even when both aliases represent Nova models.

Endpoint Coverage

Use /v1/chat/completions for the direct Nova API. AISIX can bridge compatible Responses and Anthropic Messages requests through the chat adapter. Other normalized routes work only when the direct Nova API implements the corresponding OpenAI-shaped endpoint and AISIX accepts the nova provider on that route.

Image generation, video generation, and rerank do not accept the nova provider value. See Provider Compatibility.

Troubleshooting

Symptom	Check
Upstream authentication error	Confirm the credential is a direct Nova API key, not an AWS access key.
Upstream `404`	Keep `/v1` in `api_base` and use a direct Nova model ID.
SigV4 or AWS region is required	You are using a Bedrock endpoint; follow the Bedrock setup instead.
Provider key creation returns `400`	Use `provider: "nova"` and omit `adapter`.

Next Steps

You have now connected AISIX to the direct Amazon Nova API and verified the model alias. Continue with these guides:

AWS Bedrock: configure a Bedrock-hosted Nova model with AWS credentials instead.
Model Aliases: configure routing, retry behavior, or cost metadata for the alias.
Routing and Failover: fail over between the direct Nova API and Bedrock.
Provider Compatibility: review supported proxy endpoints and provider-specific boundaries.

Prerequisites​

Configure with AISIX Cloud​

Create a Provider Key​

Create a Model​

Create a Caller API Key​

Configure with the Open-Source AISIX Gateway​

Verify the Provider Connection​

Choose Between the Nova API and Bedrock​

Endpoint Coverage​

Troubleshooting​

Next Steps​