Meta Llama API

The Meta Llama API provides direct hosted access to Llama models with API-key authentication. AISIX gives applications a stable caller-facing API while storing the upstream credential, controlling model access, and recording usage.

This page covers the Llama API on api.llama.com. It does not cover Meta's separate Model API on api.meta.ai.

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 Meta Llama API key and access to the model you plan to use.
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, a model alias, and a caller API key.

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

Create a Provider Key

Export the upstream credential:

export LLAMA_API_KEY="YOUR_LLAMA_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": "llama-api-prod",
      "provider": "llama",
      "api_key": "'"${LLAMA_API_KEY}"'",
      "api_base": "https://api.llama.com/compat/v1/",
      "allowed_environments": ["'"${ENV_ID}"'"]
    }' | jq -er '.provider_key.id'
)

echo "$PROVIDER_KEY_ID"

provider must be the catalog ID llama. Do not add adapter: AISIX derives the openai adapter for catalog providers and accepts an explicit adapter only for BYO provider keys.

The API base includes /compat/v1/. AISIX normalizes the trailing slash and appends /chat/completions, producing the upstream route https://api.llama.com/compat/v1/chat/completions.

Do not replace this base with https://api.llama.com/v1. That is Meta's native Llama API wire, whose chat response and streaming event shapes differ from OpenAI chat completions. The AISIX openai adapter requires the /compat/v1 surface.

Create a Model

List the models available to the upstream account:

curl -sS "https://api.llama.com/compat/v1/models" \
  -H "Authorization: Bearer ${LLAMA_API_KEY}" \
  | jq -r '.data[].id'

Create a caller-facing alias for one of the returned model IDs. This example uses the Llama 4 Maverick model from Meta's current official Llama API client example:

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": "llama-api-prod",
      "model_name": "Llama-4-Maverick-17B-128E-Instruct-FP8",
      "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
    }' | jq -er '.model.id'
)

echo "$MODEL_ID"

display_name is the stable alias applications send to AISIX. model_name is the exact, case-sensitive ID sent to Meta. Use an ID returned by the account's /models request because availability can change by account and API release.

Create a Caller API Key

Create a caller key limited to this model:

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": "llama-api-caller",
      "allowed_models": ["'"${MODEL_ID}"'"]
    }' | jq -er '.plaintext'
)

echo "$AISIX_API_KEY"

The plaintext caller key is returned only when the resource is created. Store it securely.

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 LLAMA_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: "llama-api-prod"
    provider: "llama"
    adapter: "openai"
    api_key: ${LLAMA_API_KEY}
    api_base: "https://api.llama.com/compat/v1/"

models:
  - display_name: "llama-api-prod"
    provider: "llama"
    model_name: "Llama-4-Maverick-17B-128E-Instruct-FP8"
    provider_key: "llama-api-prod"

api_keys:
  - display_name: "llama-api-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "llama-api-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 request through AISIX:

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer $AISIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-api-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from the Meta Llama API."
      }
    ]
  }'

AISIX resolves llama-api-prod to Llama-4-Maverick-17B-128E-Instruct-FP8, sends a bearer-authenticated request to the Llama API compatibility endpoint, and returns an OpenAI-compatible response.

Endpoint Coverage

The configured API root is Meta's OpenAI compatibility surface. AISIX route behavior is as follows:

Route	Behavior with a `llama` model alias
`/v1/chat/completions`	Supported through Meta's `/compat/v1/chat/completions` route. Llama 4 models can accept image content blocks in chat; this is vision input, not image generation.
`/v1/responses`	Supported through the AISIX cross-provider bridge, which translates the request to chat completions and converts the result back to the Responses shape. AISIX does not forward this request to a Meta Responses route. OpenAI-specific fields without a chat equivalent are ignored.
`/v1/messages`	Supported through the AISIX Anthropic-to-chat translation. `/v1/messages/count_tokens` remains limited to Anthropic-backed targets.
`/v1/embeddings` and `/v1/completions`	Not supported. Meta's `/compat/v1` root does not publish these routes.
`/v1/audio/*`, `/v1/images/generations`, `/v1/videos`, and `/v1/rerank`	Not supported. The route-specific provider gates or Meta endpoint coverage do not admit this configuration.
`/v1/batches`	Not supported. Meta's compatibility root does not publish this route.
`/v1/files` and `/v1/fine_tuning/jobs`	Unverified. Meta's compatibility root exposes matching routes, but this AISIX workflow has not been validated end to end, and the file-content route is absent upstream. Do not rely on it without testing the required operations.
`/passthrough/llama/*rest`	Available through a configured passthrough route targeting the `/compat/v1` base. Use it for compatible Meta routes that AISIX does not model, such as `/moderations`. Passthrough preserves the request and response bodies. Recognized chat, completions, and Responses envelopes record 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.

Passthrough does not rewrite a model field, so send an exact upstream model ID when the native operation requires one. The /passthrough/llama prefix assumes a passthrough route claiming it with the /compat/v1 base as its target_url and this provider key for credential injection; grant the route on the caller key's allowed_routes. If you add a second llama key for Meta's native /v1 resources, create a separate route under its own prefix bound to that key. Do not route normalized chat through the native key because its response wire is not OpenAI-compatible.

See Responses, Anthropic Messages, and Provider Compatibility for the translation and endpoint details.

Troubleshooting

Symptom	Check
Upstream `401` or `403`	Confirm `LLAMA_API_KEY` is active and the account can use the selected model.
Upstream `404`	Confirm the API base includes `/compat/v1` and copy a current model ID from the authenticated `/models` response.
Provider key creation returns `400`	Use `provider: "llama"` without an `adapter` field.
AISIX returns model access denied	Confirm the caller key's `allowed_models` contains the model resource ID.

Next Steps

You have now connected AISIX to the Meta Llama API and verified the model alias. Continue with these guides:

Model Aliases: configure routing, retry behavior, or cost metadata for the alias.
Provider Keys: rotate the upstream credential or configure provider-specific overrides.
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​

Endpoint Coverage​

Troubleshooting​

Next Steps​