Quickstart

This guide takes you from a new Aixy organization to a model response you can inspect in Activity. You need access to the Aixy dashboard, a provider account with inference access, and its credential. The example uses OpenAI; you can select another provider and use one of its model IDs instead. Model calls use your provider account and may incur charges.

1. Create your organization and select a project

Open the dashboard and choose Create an organization. Enter your organization name and slug, your name, email, and password, and complete the terms acknowledgement and registration check. Aixy creates your personal account, Owner membership, and a default project. If you already have an Aixy account, use its current password to create another organization. If you received an invitation, accept it and use the project assigned by your administrator. For an existing organization, sign in with your email and password or passkey. Aixy opens your sole organization directly or asks you to choose when you belong to several. Use Switch organization from the account menu to change where you work. Select the project in the sidebar. To create a separate application or environment, open Projects from the account menu and choose Create project. Use a recognizable name such as Development, then select it in the sidebar.

2. Connect a model provider

As an Owner, Org admin, or administrator of the selected project:

Open Providers → Add provider and choose OpenAI.
Enter your provider’s API key. This is the key from your OpenAI account, not an Aixy key.
Use Test connection to inspect authentication and model-catalog access.
Save the connection.

Keeping a project selected creates a connection for that project. Organization administrators can select All projects first to share a provider connection across projects. A project connection overrides the shared connection for that provider. A connection check does not generate text. The model request below verifies inference access. For other providers, follow the Setup guide beside the connection form in the dashboard. See Providers to understand shared connections, project overrides, and checks.

3. Choose an available model

Open Models with the same project selected. Find a conversational model on your connected provider and check that it is allowed. Copy its full provider-qualified ID, for example openai/gpt-4.1-mini. Use an ID available to your account throughout this guide. Project users can select approved models; an administrator manages model access. Models and access explains catalog information and inherited restrictions.

4. Create an Aixy project API key

Open API keys from the account menu and select Create API key:

Name the key, for example Development quickstart.
Select the project you configured. Optionally record the workload and team cost center.
Choose a lifetime and create the key.
Copy the secret from Store the new secret into a protected local environment or secret store. It is shown once.

For the terminal examples, set these variables in your local shell. Replace the placeholder key and model with your own values:

export AIXY_API_KEY="gak_your_project_key"
export AIXY_BASE_URL="https://api.aixy-gateway.com/v1"
export AIXY_MODEL="openai/gpt-4.1-mini"

For a self-hosted gateway or an active custom domain, use its API base ending in /v1. Keep the key out of source control and browser application code. You can confirm what this key can discover before making a model call:

curl --fail-with-body --silent --show-error "$AIXY_BASE_URL/models" \
  --header "Authorization: Bearer $AIXY_API_KEY"

The returned list includes direct models and configured routing models available to this project. Use an exact id from that list.

5. Try the model in Playground

Open Playground, choose your model, and open Request settings to select the new API key and Chat Completions protocol. Send a short message such as Reply with connected. Playground uses the selected key’s project, permissions, and budgets. A successful reply confirms that the provider account can execute this request. If a pricing notice appears under a hard budget, follow the pricing setup and use Recheck prices before sending.

6. Send a request from your application

Run one of these examples from a trusted local or server environment. The Python example uses only the standard library; the JavaScript example runs in Node.js with built-in fetch.

curl --fail-with-body --silent --show-error --include \
  "$AIXY_BASE_URL/chat/completions" \
  --header "Authorization: Bearer $AIXY_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{
    \"model\": \"$AIXY_MODEL\",
    \"max_completion_tokens\": 256,
    \"messages\": [{\"role\": \"user\", \"content\": \"Reply with connected.\"}]
  }"

import json
import os
from urllib.request import Request, urlopen

request = Request(
    f"{os.environ['AIXY_BASE_URL']}/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['AIXY_API_KEY']}",
        "Content-Type": "application/json",
    },
    data=json.dumps({
        "model": os.environ["AIXY_MODEL"],
        "max_completion_tokens": 256,
        "messages": [{"role": "user", "content": "Reply with connected."}],
    }).encode(),
)
with urlopen(request, timeout=60) as response:
    print("Request ID:", response.headers.get("x-request-id"))
    print(json.load(response)["choices"][0]["message"]["content"])

const response = await fetch(`${process.env.AIXY_BASE_URL}/chat/completions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AIXY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: process.env.AIXY_MODEL,
    max_completion_tokens: 256,
    messages: [{ role: "user", content: "Reply with connected." }],
  }),
});
console.log("Request ID:", response.headers.get("x-request-id"));
if (!response.ok) throw new Error(await response.text());
const completion = await response.json();
console.log(completion.choices[0].message.content);

Look for a successful response with assistant text in choices[0].message.content. Save the x-request-id response header to find this exact request in the dashboard.

7. Verify usage and apply your first controls

Open Activity, search for the request ID, and inspect its provider, model, status, timing, tokens, and cost evidence. Metadata arrives asynchronously; refresh after a short delay. Use Usage for aggregate traffic and Cost control for attributed spend and budgets. Before expanding usage:

Configure model access for the models the project should use.
Review pricing and create a budget.
Test guardrails with representative input.
Connect your editor or coding agent, or create a routing model for a stable application-facing model name.

If the first request fails

Symptom	What to check
Authentication error	Use the Aixy `gak_` key; check its project, expiry, disabled state, and revocation.
Empty model list	Check the effective provider connection, catalog access, and organization/project model blocks.
Provider access, billing, or quota error	Check the provider account and model entitlement; inspect the provider error in Activity.
Hard-budget pricing notice	Complete the applicable pricing and output bound; recheck prices in Playground.
Guardrail rejection	Ask the policy owner to review the matching policy and test the input.

See Activity for request-level diagnosis and Authentication for key lifecycle controls.

Get started

Providers and models

Model requests

Security and access

Costs and budgets

Observability

Agent tools

Administration

Integrations

1. Create your organization and select a project

2. Connect a model provider

3. Choose an available model

4. Create an Aixy project API key

5. Try the model in Playground

6. Send a request from your application

7. Verify usage and apply your first controls

If the first request fails

​1. Create your organization and select a project

​2. Connect a model provider

​3. Choose an available model

​4. Create an Aixy project API key

​5. Try the model in Playground

​6. Send a request from your application

​7. Verify usage and apply your first controls

​If the first request fails

1. Create your organization and select a project

2. Connect a model provider

3. Choose an available model

4. Create an Aixy project API key

5. Try the model in Playground

6. Send a request from your application

7. Verify usage and apply your first controls

If the first request fails