Amazon Nova API

Amazon Nova 是 Amazon 的基础模型系列，可通过直连 API 或 Amazon Bedrock 使用。本指南将直连 API 接入 AISIX，使应用可以通过网关的 OpenAI 兼容 API 调用 Nova。

此配置适用于 api.nova.amazon.com 上基于 API Key 的端点。它不同于使用 AWS 凭证、区域和 SigV4 请求签名的 Amazon Bedrock。若要通过 Bedrock 调用 Nova，请改用 Amazon Bedrock。

准备工作

开始前，请准备以下内容：

• 一套 AISIX 环境：
  • 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
  • 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 配置。配置网关以加载声明式资源文件。
• 为 Amazon Nova 直连 API 签发的 API Key。
• curl 和 jq。

使用 AISIX Cloud 配置

导出 AISIX Cloud 连接信息：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且不含尾部斜杠
# 本地私有化部署快速入门使用 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"

创建服务提供方密钥

导出 Nova API Key：

export NOVA_API_KEY="YOUR_NOVA_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": "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 通过社区目录接受 nova，并派生使用 Bearer 身份认证的 openai 适配器。不要在该目录服务提供方密钥上发送 adapter。

AISIX 会在配置的 API 基础 URL 后追加 /chat/completions。请保留值中的 /v1；仅使用 https://api.nova.amazon.com 主机将指向错误路由。

创建模型

为 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"

请使用 Amazon Nova 开发者文档发布的精确模型 ID。Nova 直连 API 和 Bedrock 访问同一模型系列时可能使用不同的标识符，因此不要把 Bedrock 模型或推理配置文件 ARN 复制到此字段。

创建调用方 API Key

创建一个只能访问 Nova 别名的调用方密钥：

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"

使用开源 AISIX 网关配置

导出上游凭证，并选择应用将发送给网关的调用方 API Key：

export NOVA_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

对于新网关，请使用此完整资源文件。对于现有网关，请将这些条目合并到其当前文件中，并保留其他资源：

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"

如果 AISIX 安装在本地，请在加载前验证文件：

aisix validate --resources resources.yaml

验证后，在网关进程环境中提供文件引用的环境变量，再启动网关。仅当这些变量已经可供进程使用时，才重新加载现有网关；否则，请使用更新后的环境重启网关。

如果使用 Docker，请调整开源 AISIX 网关快速入门中的验证和启动命令。挂载此 resources.yaml 文件，并在两条命令中使用 -e 传入它引用的每个环境变量。资源加载后，准备下文共用的验证请求：

export AISIX_API_KEY="$CALLER_API_KEY"

验证服务提供方连接

导出 AISIX 网关 Origin：

# AISIX_PROXY 不含尾部斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

通过 AISIX 代理发送 Chat Completions 请求：

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 会把 nova-2-lite-v1 发送到 https://api.nova.amazon.com/v1/chat/completions，并在 Bearer 请求头中携带 Nova API Key。

在 Nova API 与 Bedrock 之间选择

账户路径	AISIX 服务提供方	凭证和适配器
Nova 直连 API	nova	使用 openai 适配器的 Nova API Key
Amazon Bedrock	amazon-bedrock	使用 bedrock 适配器的 AWS 访问凭证

请为两条路径使用不同的服务提供方密钥。即使两个别名都代表 Nova 模型，这也能明确区分凭证轮换、账户归因和故障转移行为。

端点覆盖范围

Nova 直连 API 使用 /v1/chat/completions。AISIX 可以通过聊天适配器桥接兼容的 Responses 和 Anthropic Messages 请求。只有当 Nova 直连 API 实现了对应的 OpenAI 形态端点，并且 AISIX 在该路由上接受 nova 服务提供方时，其他标准化路由才能工作。

图像生成、视频生成和 rerank 不接受 nova 服务提供方值。请参阅服务提供方兼容性。

故障排除

现象	检查项
上游身份认证错误	确认凭证是 Nova 直连 API Key，而不是 AWS Access Key。
上游 404	在 api_base 中保留 /v1，并使用 Nova 直连模型 ID。
要求 SigV4 或 AWS 区域	当前使用的是 Bedrock 端点；请改为按照 Bedrock 配置操作。
创建服务提供方密钥返回 400	使用 provider: "nova" 并省略 adapter。

后续步骤

你已将 AISIX 接入 Amazon Nova 直连 API，并验证了模型别名。接下来可以阅读：

• AWS Bedrock：改为使用 AWS 凭证配置 Bedrock 托管的 Nova 模型。
• 模型别名：为别名配置路由、重试行为或成本元数据。
• 路由和故障转移：在 Nova 直连 API 和 Bedrock 之间进行故障转移。
• 服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。