Quickstart

Access leading AI models (GPT-4o, Gemini, and others) through a single unified API. Initial setup takes just a few minutes. New accounts can make up to 10 free requests per hour.

If you are a manager and simply want to test a model to evaluate its performance, for instance in content generation, the quickest approach is to use our Playground. It offers an intuitive, user-friendly interface—no coding required.

Programmatic API calls are best suited for developers who want to integrate a model into their own apps.

Here, you'll learn how to start using our API in your code. The following steps must be completed regardless of which of our models you plan to call:

Let's walk through an example of connecting to the free-tier Gemma 3 model via REST API. After completing the steps, you will be able to generate text with this model at no cost.

Generating an AIML API Key

What is an API Key?

You can find your AIML API key on the account page.

An AIML API key is a credential that grants you access to our API from your code. It is a sensitive string that is shown only at creation time and should be kept confidential. Do not share this key with anyone, as it could be misused without your knowledge. If you lose it, generate a new key from your dashboard.

⚠️ Note that API keys from third-party organizations cannot be used with our API: you need an AIML API Key.

To use the AIML API, you need to create an account and generate an AIML API key. Follow these steps:

Create an Account: Visit the AI/ML API website and create an account.
Generate an API Key: After logging in, navigate to your account dashboard and generate your API key. Ensure that key is enabled on UI.

Choosing the Development Environment

Each language has recommended environments for running code samples.

cURL

REQBIN is a web-based REST client that lets you quickly run cURL requests directly in your browser, without installing any tools.
Git Bash (Windows) or the built-in Terminal (macOS/Linux) allow you to run cURL examples and other command-line tools locally.

Python

Jupyter Notebook is a popular online environment for running Python code and is the fastest option if you do not want to install anything locally.
Visual Studio Code (VS Code) is a lightweight and widely used code editor that supports both Python and Node.js. It is suitable for running and debugging local examples and for working on real projects.

JavaScript

Visual Studio Code (VS Code)

In the examples below for cURL, JavaScript and Python, we use the REST API. This approach works with all of our APIs, but it is not the only way to integrate. You can use other supported SDKs.

Making an API Call

Based on your environment, you will call our API differently. Below are three common ways to call our API using two popular languages: cURL (a command-line format for making HTTP requests rather than a programming language), Python, and JavaScript (NodeJS).

If you want to get started really quickly, choose one of the four expandable sections below. Each one contains instructions for calling our model using different tools and environments. The first two options are especially simple and suitable even for beginners.

For completeness, the same example is explained in detail in the Code Step-by-Step section.

curl -L \
  --request POST \
  --url 'https://api.aimlapi.com/v1/chat/completions' \
  --header 'Authorization: Bearer <YOUR_AIMLAPI_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "google/gemma-3-4b-it",
    "messages": [
      {
        "role": "user",
        "content": "Tell me about San Francisco"
      }
    ],
    "temperature": 0.7,
    "max_tokens": 512
  }'

userPrompt = 'Tell me about San Francisco' // insert your request here

async function main() {
  const response = await fetch('https://api.aimlapi.com/v1/chat/completions', {
    method: 'POST',
    headers: {
      // Insert your AIML API Key instead of <YOUR_AIMLAPI_KEY>
      'Authorization': 'Bearer <YOUR_AIMLAPI_KEY>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'google/gemma-3-4b-it',
      messages:[
          {
              role:'user',
              content: userPrompt
          }
      ],
      temperature: 0.7,
      max_tokens: 512,
    }),
  });

  const data = await response.json();
  const answer = data.choices[0].message.content;
  
  console.log('User:', userPrompt);
  console.log('AI:', answer);
}

main();

import requests 

user_prompt = "Tell me about San Francisco"  # insert your request here

response = requests.post(
    "https://api.aimlapi.com/v1/chat/completions",
    headers={
        # Insert your AIML API Key instead of <YOUR_AIMLAPI_KEY>:
        "Authorization":"Bearer <YOUR_AIMLAPI_KEY>",
        "Content-Type":"application/json"
    },
    json={
        "model":"google/gemma-3-4b-it",
        "messages":[  
            {
                "role":"user",
                "content": user_prompt
            }
        ],
        "temperature": 0.7,
        "max_tokens": 512,
    }
)

data = response.json()
answer = data["choices"][0]["message"]["content"]

print("User:", user_prompt)
print("AI:", answer)

⭐ How to run a cURL example in a web-based REST client (REQBIN)

Calling the API via cURL through a web service like this is the simplest and fastest method, requiring no additional libraries. However, there is a downside: cURL is not a programming language, which means it has very limited capabilities for adding logic—only API calls, no loops or conditions. You can’t even extract just the specific field with the model’s text response—cURL returns the model’s full output, as you’ll see below.

1. Copy the cURL example above and paste it into a text editor, such as Notepad or Notepad++.

2. Replace the placeholder <YOUR_AIMLAPI_KEY> with your actual AIMLAPI Key.

3. If needed, modify the prompt (the content field).

4. Copy the modified example, go to the REQBIN website, paste it into the designated field and click Run:

5. After the model processes your request, the model’s full output will be shown directly below the input field.

Pro tip: try experimenting with the three different ways of displaying the model’s output. Some are more readable than others.

⭐ How to run a Python example in an online Jupyter Notebook

The second fastest option, and a much more convenient choice, while offering more flexibility for customizing how the output is displayed in code.

1. When you open Jupyter Notebook for the first time, select “Python 3.13 (XPython)” in the pop-up window to indicate the programming language kernel you will be working with:

In some browsers, the kernel selection may look different:

2. Enter the following command in the first cell to install the requests library:

%pip install requests

Click the Run button in the toolbar above the cell to execute it:

3. Paste our example into the second cell, replace the placeholder with your AIMLAPI Key, then click the Run button in the toolbar:

4. After the model processes your request, the result will be shown directly below the cell:

How to run a Python example locally from the command line (without an IDE)

Let's start from very beginning. We assume you already installed Python (with venv), if not, here a guide for the beginners.

Create a new folder for test project, name it as aimlapi-welcome and change to it.

mkdir ./aimlapi-welcome
cd ./aimlapi-welcome

(Optional) If you use IDE then we recommend to open created folder as workspace. On example, in Visual Studio Code you can do it with:

code .

Run a terminal inside created folder and create virtual envorinment with a command:

python3 -m venv ./.venv

Activate created virtual environment:

# Linux / Mac
source ./.venv/bin/activate
# Windows
./.venv/bin/Activate.bat

Install requirement dependencies. In our case (REST API SDK) we need only request library:

pip install requests

Create new file and name it as travel.py:

touch travel.py

Paste following content inside this travel.py and replace <YOUR_AIMLAPI_KEY> with your API key you got on first step:

import requests 

user_prompt = "Tell me about San Francisco"

response = requests.post(
    "https://api.aimlapi.com/v1/chat/completions",
    headers={
        # Insert your AIML API Key instead of <YOUR_AIMLAPI_KEY>:
        "Authorization":"Bearer <YOUR_AIMLAPI_KEY>",
        "Content-Type":"application/json"
    },
    json={
        "model":"google/gemma-3-4b-it",
        "messages":[
            {
                "role":"user",
                "content": user_prompt
            }
        ],
        "temperature": 0.7,
        "max_tokens": 512,
    }
)

data = response.json()
answer = data["choices"][0]["message"]["content"]

print("User:", user_prompt)
print("AI:", answer)

Run the application:

python3 ./travel.py

If you done all correct, you will see following output:

User: Tell me about San Francisco
AI:  San Francisco, located in northern California, USA, is a vibrant and culturally rich city known for its iconic landmarks, beautiful vistas, and diverse neighborhoods. It's a popular tourist destination famous for its iconic Golden Gate Bridge, which spans the entrance to the San Francisco Bay, and the iconic Alcatraz Island, home to the infamous federal prison.

The city's famous hills offer stunning views of the bay and the cityscape. Lombard Street, the "crookedest street in the world," is a must-see attraction, with its zigzagging pavement and colorful gardens. Ferry Building Marketplace is a great place to explore local food and artisanal products, and the Pier 39 area is home to sea lions, shops, and restaurants.

San Francisco's diverse neighborhoods each have their unique character. The historic Chinatown is the oldest in North America, while the colorful streets of the Mission District are known for their murals and Latin American culture. The Castro District is famous for its LGBTQ+ community and vibrant nightlife.

How to run a JavaScript example locally from the command line (without an IDE)

We assume you already have Node.js installed. If not, here is a guide for beginners.

Create a new folder for the example project:

mkdir ./aimlapi-welcome
cd ./aimlapi-welcome

Create a project file:

npm init -y

Create a file with the source code:

touch ./index.js

And paste the following content to the file and save it:

async function main() {
  const response = await fetch('https://api.aimlapi.com/v1/chat/completions', {
    method: 'POST',
    headers: {
      // Insert your AIML API Key instead of <YOUR_AIMLAPI_KEY>
      'Authorization': 'Bearer <YOUR_AIMLAPI_KEY>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'google/gemma-3-4b-it',
      messages:[
          {
              role:'user',
              content: 'Tell me about San Francisco'  // Insert your prompt here
          }
      ],
      temperature: 0.7,
      max_tokens: 256,
    }),
  });

  const data = await response.json();
  console.log(JSON.stringify(data, null, 2));
}

main();

Run the file:

./index.js

You will see a response that looks like this:

User: Tell me about San Francisco
AI: San Francisco, located in the northern part of California, USA, is a vibrant and culturally rich city known for its iconic landmarks, beautiful scenery, and diverse neighborhoods.

The city is famous for its iconic Golden Gate Bridge, an engineering marvel and one of the most recognized structures in the world. Spanning the Golden Gate Strait, this red-orange suspension bridge connects San Francisco to Marin County and offers breathtaking views of the San Francisco Bay and the Pacific Ocean.

Code Step-by-Step

Below is a step-by-step explanation of the same API call in three variants: cURL, JavaScript, and Python. All three examples send an identical request to the google/gemma-3-4b-it chat model.

cURL

1. Command start

curl -L \

Runs the cURL HTTP client. The -L flag tells cURL to follow redirects (if any).

2. HTTP method

--request POST \

Specifies that the request uses the POST method.

3. Endpoint

--url 'https://api.aimlapi.com/v1/chat/completions' \

The full endpoint URL used to call chat models.

4. Authorization header

--header 'Authorization: Bearer <YOUR_AIMLAPI_KEY>' \

Sends your AIMLAPI key in the Authorization header.

5. Content type

--header 'Content-Type: application/json' \

Indicates that the request body is JSON.

6. Request body

--data '{
  "model": "google/gemma-3-4b-it",
  "messages": [
    {
      "role": "user",
      "content": "Tell me about San Francisco"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 512
}'

This is the payload sent to the API:

model – the model identifier.
messages – the chat history.
- role: "user" – the user message.
- content – the user prompt.
temperature – controls output randomness.
max_tokens – the maximum number of tokens in the response.

These are the input parameters used to tell the endpoint—which in this case generates text answers—what exactly we want it to produce.

With the parameters shown above, we are effectively asking the API to use the google/gemma-3-4b-it model and generate a reasonably vivid and engaging description of San Francisco, limited to roughly 300–350 words— with the temperature and max_tokens parameters controlling the creativity and approximate length of the output, respectively.

7. Response

In the cURL example, you receive the entire JSON response. No fields are extracted — cURL simply prints the raw output.

JavaScript (Node.js)

1. Define the user prompt

userPrompt = 'Tell me about San Francisco'

Stores the text of the user request.

2. Call the API

const response = await fetch(
  'https://api.aimlapi.com/v1/chat/completions',
  { ... }
);

Sends an HTTP request to the endpoint.

3. HTTP method

method: 'POST',

Specifies that the request uses the POST method.

4. Headers

headers: {
  'Authorization': 'Bearer <YOUR_AIMLAPI_KEY>',
  'Content-Type': 'application/json',
},

Sends your AIMLAPI key in the Authorization header.
Indicates that the request body is JSON.

5. Request body

body: JSON.stringify({
  model: 'google/gemma-3-4b-it',
  messages: [
    {
      role: 'user',
      content: userPrompt
    }
  ],
  temperature: 0.7,
  max_tokens: 512,
}),

This is the payload sent to the API:

model – the model identifier.
messages – the chat history.
- role: "user" – the user message.
- content – the user prompt.
temperature – controls output randomness.
max_tokens – the maximum number of tokens in the response.

These are the input parameters used to tell the endpoint—which in this case generates text answers—what exactly we want it to produce.

6. Parse the response

const data = await response.json();

Converts the API response into a JavaScript object.

7. Extract the model’s text output

const answer = data.choices[0].message.content;

Reads the text of the first generated message.

8. Print the result

console.log('User:', userPrompt);
console.log('AI:', answer);

Output formatting: from the model’s full response, only the generated text is extracted, and it is presented together with the original prompt in a dialogue-style format.

Python

1. Import the HTTP library

import requests

The requests library is used to send HTTP requests.

2. Define the user prompt

user_prompt = "Tell me about San Francisco"

Stores the text of the user query.

3. Call the API

response = requests.post(
    "https://api.aimlapi.com/v1/chat/completions",
    ...
)

Sends a POST request to the endpoint.

4. Headers

headers={
    "Authorization": "Bearer <YOUR_AIMLAPI_KEY>",
    "Content-Type": "application/json"
},

Sends your AIMLAPI key in the Authorization header.
Indicates that the request body is JSON.

5. Request body

json={
    "model": "google/gemma-3-4b-it",
    "messages": [
        {
            "role": "user",
            "content": user_prompt
        }
    ],
    "temperature": 0.7,
    "max_tokens": 512,
}

This is the payload sent to the API:

model – the model identifier.
messages – the chat history.
- role: "user" – the user message.
- content – the user prompt.
temperature – controls output randomness.
max_tokens – the maximum number of tokens in the response.

These are the input parameters used to tell the endpoint—which in this case generates text answers—what exactly we want it to produce.

6. Parse the response

data = response.json()

Converts the JSON response into a Python dictionary.

7. Extract the model’s text output

answer = data["choices"][0]["message"]["content"]

Reads the text of the first generated message.

8. Print the result

print("User:", user_prompt)
print("AI:", answer)

Output formatting: from the model’s full response, only the generated text is extracted, and it is presented together with the original prompt in a dialogue-style format.

Future Steps

PreviousDocumentation Map NextRequesting more advanced models

Last updated 8 days ago

Was this helpful?

hashtagGenerating an AIML API Key

hashtagChoosing the Development Environment

hashtagMaking an API Call

hashtagCode Step-by-Step

hashtagFuture Steps

Generating an AIML API Key

Choosing the Development Environment

Making an API Call

Code Step-by-Step

Future Steps