AIML API

AIML API gives one OpenAI-compatible endpoint for models from many vendors. Behind Verdictan, your AIML API key stays on the gateway, and your application calls the gateway with its Verdictan application token.

AIML API model IDs carry a vendor prefix. Always use the full ID from the AIML API catalog.

Before you start

• A working gateway from the quickstart.
• An AIML API key, and the full ID of one model that your account can use.
• The gateway startup command, and a separate application token for test requests.

Configure the provider

policy-config.yaml

pack:
  name: aimlapi-integration
  version: 1.0.0
  enabled: true
policies:
  chain:
    - prompt-injection
providers:
  targets:
    - id: aimlapi-primary
      provider: aimlapi
      model: "replace-with-aimlapi-model-id"
      base_url: https://api.aimlapi.com
      secret_key_ref:
        env: VERDICTAN_AIMLAPI_API_KEY

The gateway sends the key from VERDICTAN_AIMLAPI_API_KEY as a Bearer token. Keep it out of the file and out of application requests.

Start and verify

For a terminal workflow, deploy this configuration with CLI 0.1.14 or later. Check In sync before the request below. Keep the AIMLAPI key in the gateway environment.

With the quickstart in Docker, follow the container steps instead of steps 1 to 3.

1. In the gateway terminal, set the key and lint the file:

   export VERDICTAN_AIMLAPI_API_KEY="<provider-api-key>"
   verdictan policy lint --file policy-config.yaml

2. Restart the test gateway with the key in its environment.

3. Deploy the file to the test agent in Configurations. If that agent already runs pack.version 1.0.0, increase the version first. Then wait for the gateway log line connected read model refresh applied updated config with your version as config_version. Try the change on a test gateway has the steps.

4. In a second terminal, send a request for the configured model:

   export VERDICTAN_CLIENT_TOKEN="<application-token>"
   curl --fail-with-body http://127.0.0.1:41002/v1/chat/completions \
     -H "Authorization: Bearer ${VERDICTAN_CLIENT_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{"model":"replace-with-aimlapi-model-id","messages":[{"role":"user","content":"Reply with Hello."}]}'

choices[0].message.content contains the reply, and the request appears in History when capture is on, or in the delivered events. A model list or health check does not prove a provider call.

Supported requests

Request	Support
Chat Completions	Yes, including streaming and tool calls
Messages	Translated to Chat Completions
Embeddings	Yes, with an embedding model. The policy chain does not run on embeddings.
Responses, image input, response_format, parallel tool calls	No

A model in the AIML API catalog can support more than this adapter does. Test each feature with your model.

Failure behavior

Problem	What to check
401 from the gateway	The application token is active, and the key is set on the gateway host.
Provider authentication error	VERDICTAN_AIMLAPI_API_KEY is set in the gateway process. Restart the gateway.
Model not found	The request uses the full model ID of the target, and your account can use it.
capability.unsupported_family	The request uses a family from the table above.
Provider 429 or another upstream error	The response body and your AIML API quota. See Error Handling.

Limits

• Model names, prices, rate limits, and data terms are in the AIML API documentation. Verdictan does not publish them.
• Streaming, tools, and embeddings vary by model. Test each one before production.
• A listener on a non-loopback address needs TLS and network controls.

Next steps

• Provider Configuration: target fields, routing, and fallback.
• Runtime Request Families: request families and their policy stages.