# Supported SDKs

This page describes the SDK[^1]s that can be used to call our API.

<details>

<summary>Key Definitions &#x26; Notes</summary>

The **REST API** itself is *not* an SDK. It is the **server-side interface** that exposes your models over HTTP. It defines endpoints, HTTP methods (POST/GET), required headers, and the structure of request and response JSON. Essentially, it’s the “contract” the server provides for clients to interact with models programmatically.

***

An **SDK** (Software Development Kit) is a **client-side library** that wraps around the REST API. It handles details like building HTTP requests, serializing/deserializing JSON, error handling, retries, and sometimes additional conveniences.

You can skip the SDK and call the REST API directly via cURL, fetch, requests, etc.\
The SDK just makes your life easier; the REST API is the “core interface” the SDK talks to.

***

The following flow shows how a request travels from your code to the model and back. Using an SDK is optional — it simply wraps the REST API for convenience.

> Your code → SDK (optional) → REST API → Model → REST API → SDK → Your code

</details>

{% hint style="info" %}
Comparing requests made with raw REST API and different SDKs, pay attention to the following common aspects:

* how the Authorization header and the AIML API key are provided,
* how the `POST` method and the endpoint URL are specified,
* how the input parameters are passed.
  {% endhint %}

{% hint style="success" %}
Also take a look at the [**INTEGRATIONS**](https://docs.aimlapi.com/integrations/our-integration-list) section — it covers many third-party services and libraries (workflow platforms, coding assistants, etc.) that allow you to integrate our models in various ways.
{% endhint %}

***

## REST API

We use the REST API because it’s fast, simple, and easy to understand. Only in Python do you need to import a separate library (`requests`), while cURL and JavaScript (Node.js) already have built-in support for HTTP requests. Therefore, REST API is used in the documentation examples for *all* of our models.

### Installation

In Python examples, you need to import the `requests` library. The Node.js and cURL examples do not require any additional imports.

Install the library first:

{% tabs %}
{% tab title="Shell" %}

```bash
pip install requests
```

{% endtab %}
{% endtabs %}

Import the library in every Python code snippet where you make calls to the REST API.

{% tabs %}
{% tab title="Python" %}

```python
import requests
```

{% endtab %}
{% endtabs %}

### Authorization

Our API authorization is based on a Bearer token. Include it in the `Authorization` HTTP header within the request. Example:

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
  headers: {
    Authorization: "Bearer <YOUR_AIMLAPI_KEY>",
  },
```

{% endtab %}

{% tab title="Python" %}

```python
    headers={
        "Authorization": "Bearer <YOUR_AIMLAPI_KEY>",
    },
```

{% endtab %}
{% endtabs %}

### Request Example

{% tabs %}
{% tab title="cURL" %}

```ruby
curl --request POST \
  --url https://api.aimlapi.com/chat/completions \
  --header 'Authorization: Bearer <YOUR_AIMLAPI_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "google/gemma-3-4b-it",
    "messages": [
        {
            "role": "user",
            "content": "What kind of model are you?"
        }
    ],
    "max_tokens": 512
}'
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
fetch("https://api.aimlapi.com/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer <YOUR_AIMLAPI_KEY>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "google/gemma-3-4b-it",
    messages: [
      {
        role: "user",
        content: "What kind of model are you?",
      },
    ],
    max_tokens: 512,
  }),
})
  .then((res) => res.json())
  .then(console.log);
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import json  # for getting a structured output with indentation

response = requests.post(
    url="https://api.aimlapi.com/chat/completions",
    headers={
        "Authorization": "Bearer <YOUR_AIMLAPI_KEY>",
        "Content-Type": "application/json",
    },
    data=json.dumps(
        {
            "model": "google/gemma-3-4b-it",
            "messages": [
                {
                    "role": "user",
                    "content": "What kind of model are you?",
                },
            ],
            "max_tokens": 512
        }
    ),
)

response.raise_for_status()
print(response.json())
```

{% endtab %}
{% endtabs %}

***

## OpenAI

The OpenAI SDK is a convenient library that simplifies working with our API. It automatically handles JSON responses, includes built-in error handling and retry logic, and provides simple, easy-to-use methods for all API features such as chat, embeddings, and completions.

<details>

<summary>The AI features that the OpenAI SDK supports</summary>

* Streaming
* Completions
* Chat Completions
* Audio
* Beta Assistants
* Beta Threads
* Embeddings
* Image Generation
* File Uploads

{% hint style="info" %}
Therefore, we don’t currently have the option to call video models or voice / speech models (STT and TTS) through this SDK.
{% endhint %}

</details>

### Installation

<details>

<summary>Python</summary>

1\. Make sure you have Python 3.7+ and `pip` installed.

2\. Install the OpenAI SDK via terminal or Jupyter Notebook:

```bash
pip install openai
```

> In Jupyter Notebook, you can also use:
>
> ```python
> %pip install openai
> ```

3\. Import the SDK:

```python
import openai
```

***

</details>

<details>

<summary>JavaScript (Node.js)</summary>

1\. Make sure you have Node.js 18+ and npm installed.

2\. Install the OpenAI SDK in your project:

```bash
npm install openai
```

3\. Import the SDK and initialize the client:

```js
import OpenAI from "openai";
```

</details>

### Example Code

{% tabs %}
{% tab title="Python" %}
{% code overflow="wrap" %}

```python
from openai import OpenAI

# Insert your AIML API key in the quotation marks instead of <YOUR_AIMLAPI_KEY>:
api_key = "<YOUR_AIMLAPI_KEY>" 
base_url = "https://api.aimlapi.com/v1"
user_prompt = "Tell me about San Francisco"

api = OpenAI(api_key=api_key, base_url=base_url)


def main():
    completion = api.chat.completions.create(
        model="google/gemma-3-4b-it",
        messages=[
            {
              "role": "user", 
              "content": user_prompt
            },
        ],
        temperature=0.7,
        max_tokens=256,
    )

    response = completion.choices[0].message.content
    print("User:", user_prompt)
    print("AI:", response)


if __name__ == "__main__":
    main()
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}
{% code overflow="wrap" %}

```javascript
#!/usr/bin/env node

const OpenAI = require("openai");
const baseURL = "https://api.aimlapi.com/v1";
const apiKey = "<YOUR_AIMLAPI_KEY>";
const systemPrompt = "You are a travel agent. Be descriptive and helpful.";
const userPrompt = "Tell me about San Francisco";

const api = new OpenAI({
  apiKey,
  baseURL,
});

const main = async () => {
  try {
    const completion = await api.chat.completions.create({
      model: "gpt-4o",
      messages: [
        {
          role: "system",
          content: systemPrompt,
        },
        {
          role: "user",
          content: userPrompt,
        },
      ],
      temperature: 0.7,
      max_tokens: 256,
    });

    const response = completion.choices[0].message.content;

    console.log("User:", userPrompt);
    console.log("AI:", response);
  } catch (error) {
      console.error("Error:", error.message);
  }
};

main();
```

{% endcode %}
{% endtab %}
{% endtabs %}

***

## AI/ML API Python library

We have started developing our own SDK to simplify the use of our service.

{% hint style="success" %}
If you’d like to contribute to expanding its functionality, feel free to reach out to us on [**Discord**](https://discord.com/invite/hvaUsJpVJf)!
{% endhint %}

### Installation

After obtaining your AIML API key, create an .env file and copy the required contents into it.

```shell
touch .env
```

Copy the code below, paste it into your `.env` file, and set your API key in `AIML_API_KEY="<YOUR_AIMLAPI_KEY>"`, replacing `<YOUR_AIMLAPI_KEY>` with your actual key:

```shell
AIML_API_KEY = "<YOUR_AIMLAPI_KEY>"
AIML_API_URL = "https://api.aimlapi.com/v1"
```

Install the package:

```shell
# install from PyPI
pip install aimlapi-sdk-python
```

### Request Example

{% tabs %}
{% tab title="Python" %}
{% code overflow="wrap" %}

```python
from aiml_api import AIML_API

api = AIML_API()

completion = api.chat.completions.create(
    model = "mistralai/Mistral-7B-Instruct-v0.2",
    messages = [
        {"role": "user", "content": "Explain the importance of low-latency LLMs"},
    ],
    temperature = 0.7,
    max_tokens = 256,
)

response = completion.choices[0].message.content
print("AI:", response)
```

{% endcode %}
{% endtab %}
{% endtabs %}

To execute the script, use:

```shell
python3 <your_script_name>.py
```

***

## Next Steps

* [Check our full list of model IDs](https://docs.aimlapi.com/api-references/model-database)
* [Browse and compare AI models, including GPT, Claude, and many others, using the Playground](https://aimlapi.com/app/)
* [Learn more about special text model capabilities](https://docs.aimlapi.com/capabilities)
* [Join the community: get help and share your projects in our Discord](https://discord.com/invite/hvaUsJpVJf)

[^1]: An SDK (Software Development Kit) is a **client-side library** that wraps around the REST API.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aimlapi.com/quickstart/supported-sdks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.