Libraries

Set up your development environment to use the AvalAI API with an SDK in your preferred language.

This page covers setting up your local development environment to use the AvalAI API. AvalAI uses the official OpenAI SDKs with a custom base URL, allowing you to leverage well-maintained libraries while connecting to AvalAI's services.

Create and export an API key

Before you begin, create an API key in the dashboard, which you'll use to securely access the API. Store the key in a safe location, like a .zshrc file or another text file on your computer. Once you've generated an API key, export it as an environment variable in your terminal.

Bash

# Export an environment variable on macOS or Linux systems
export AVALAI_API_KEY="aa-YOUR_API_KEY"

powershell:# Export an environment variable in PowerShell
setx AVALAI_API_KEY "aa-YOUR_API_KEY"

The examples below pass AVALAI_API_KEY explicitly and set AvalAI's custom base URL on each client.

SDK Options

AvalAI supports three approaches for accessing AI models:

1. OpenAI-Compatible SDKs (Unified approach) - Use OpenAI's SDKs to access all models from multiple providers with consistent syntax
2. Anthropic Official SDKs (Native approach) - Use Anthropic's official SDKs to access models from multiple providers (Anthropic, OpenAI, AWS Bedrock, Vertex AI, and Gemini) with native syntax
3. Google GenAI SDK (Native approach) - Use Google's official GenAI SDK for native access to Gemini models with Google's native API schema

Choosing Responses vs Chat Completions

Use the official OpenAI SDKs with AvalAI's baseURL for both /v1/responses and /v1/chat/completions:

• Start new text, reasoning, and tool workflows with Responses when the model supports it. Send input, optional instructions, and read response.output_text.
• Keep Chat Completions for existing integrations that already use messages, frameworks that expect chat completions, or models that only expose chat compatibility.
• Migrate incrementally by reusing simple messages as input, moving system prompts to instructions, and replacing choices[0].message.content with output_text.

See Responses vs. Chat Completions for the full migration path.

SDK freshness notes

OpenAI's SDKs move quickly as the Responses API adds new capabilities. Pin versions in production, read each SDK changelog before major upgrades, and keep a raw HTTP fallback for newly released AvalAI routes or provider-specific parameters that your SDK has not exposed yet. When an SDK example mentions OPENAI_API_KEY, use AVALAI_API_KEY and set baseURL / base_url to https://api.avalai.ir/v1.

Production SDK checklist

OpenAI's library and API reference docs emphasize that SDK choice is only one part of a production integration. Apply these rules when adapting SDK examples to AvalAI:

• Use the right client layer: use official OpenAI SDKs for direct /v1/responses, /v1/chat/completions, audio, images, embeddings, and files calls; use raw HTTP when a newly released AvalAI route or provider-native parameter is not exposed by the SDK yet.
• Keep secrets server-side: never expose AVALAI_API_KEY in browser, mobile, or public repository code. If a browser flow needs model access, proxy it through your backend.
• Log trace IDs: capture AvalAI's avalai-request-id from response headers and include your own X-Client-Request-Id when you already have an internal trace ID. Keep it ASCII, unique per request, and short enough for the Response Headers constraints.
• Separate SDK surfaces: OpenAI-compatible SDK examples usually need https://api.avalai.ir/v1; Anthropic and Google-native examples on this page intentionally use https://api.avalai.ir without /v1.
• Handle retries deliberately: rely on SDK retry behavior for transient network errors, but still implement app-level idempotency, backoff, and user-visible failure states for tool calls, payments, file uploads, and long-running jobs.
• Treat Agents SDK as orchestration guidance: OpenAI recommends the Agents SDK for tool orchestration, handoffs, guardrails, tracing, and sandbox execution. Use it as an architectural reference with AvalAI only after verifying the selected model client, base URL, and tool features work with your route.

Timeouts and long-running requests

OpenAI's SDK guidance notes that official SDKs have request timeouts and automatic retries for some transient timeout failures. For AvalAI, configure timeouts explicitly when a request can run longer than an ordinary chat turn: flex service tier, long documents, deep-research style workflows, large file inputs, slow tools, or app-managed background jobs.

Use a longer SDK timeout only for workloads that can safely wait. For interactive UX, prefer streaming, progress messages, shorter max_output_tokens, lower reasoning.effort, or an app-managed job that the user can resume.

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
    timeout=900.0,  # 15 minutes for long-running requests
)

response = client.with_options(timeout=900.0).responses.create(
    model="gpt-5.6-luna",
    input="Analyze this long report and return a concise risk summary...",
    max_output_tokens=800,
)

print(response.output_text)

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
  timeout: 900_000, // 15 minutes for long-running requests
});

const response = await client.responses.create(
  {
    model: "gpt-5.6-luna",
    input: "Analyze this long report and return a concise risk summary...",
    max_output_tokens: 800,
  },
  { timeout: 900_000 }
);

console.log(response.output_text);

When adding retries around SDK calls, retry only idempotent operations automatically. For writes, payments, file uploads, webhook processing, or tool executions with side effects, store an idempotency key or job ID first, then retry from your application state rather than blindly replaying the same action.

Install an official SDK

Jump to your language:

JavaScript / TypeScriptNode.js, Deno, Bun — npm install openaiPythonOfficial OpenAI SDK — pip install openai.NET / C#Microsoft-supported — dotnet add package OpenAIJavaMaven dependency for openai-javaGoOfficial Go helper for the OpenAI APIRubyOfficial Ruby SDK — gem "openai"OpenAI CLITerminal workflows with an AvalAI raw HTTP fallbackCommunityPHP, Ruby, Rust, and more community SDKs

Javascript

To use the AvalAI API in server-side JavaScript environments like Node.js, Deno, or Bun, you can use the official OpenAI SDK for TypeScript and JavaScript. Get started by installing the SDK using npm or your preferred package manager:

npm install openai

With the OpenAI SDK installed, create a file called example.mjs and copy the example code into it:

import OpenAI from "openai";
const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1", // AvalAI API endpoint
});

const response = await client.responses.create({
  model: "gpt-5.6-luna",
  input: "Write a one-sentence bedtime story about a unicorn.",
});

console.log(response.output_text);

Execute the code with node example.mjs (or the equivalent command for Deno or Bun). In a few moments, you should see the output of your API request.

Python

To use the AvalAI API in Python, you can use the official OpenAI SDK for Python. Get started by installing the SDK using pip:

pip install openai

With the OpenAI SDK installed, create a file called example.py and copy the example code into it:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

response = client.responses.create(
    model="gpt-5.6-luna", input="Write a one-sentence bedtime story about a unicorn."
)

print(response.output_text)

Execute the code with python example.py. In a few moments, you should see the output of your API request.

.NET

In collaboration with Microsoft, OpenAI provides an officially supported API client for C# that can be used with AvalAI. You can install it with the .NET CLI from NuGet.

dotnet add package OpenAI

A simple API request to Chat Completions would look like this:

using OpenAI.Chat;

ChatClient client = new(
  model: "gpt-5.6-luna",
  apiKey: Environment.GetEnvironmentVariable("AVALAI_API_KEY"),
  endpoint: new Uri("https://api.avalai.ir/v1") // AvalAI API endpoint
);

ChatCompletion completion = client.CompleteChat("Say 'this is a test.'");

Console.WriteLine($"[ASSISTANT]: {completion.Content[0].Text}");

Responses API version:

using OpenAI.Responses;

OpenAIResponseClient client = new(
  model: "gpt-5.6-luna",
  apiKey: Environment.GetEnvironmentVariable("AVALAI_API_KEY"),
  endpoint: new Uri("https://api.avalai.ir/v1") // AvalAI API endpoint
);

OpenAIResponse response = client.CreateResponse("Say 'this is a test.'");

Console.WriteLine($"[ASSISTANT]: {response.GetOutputText()}");

Java

OpenAI provides an API helper for the Java programming language that can be used with AvalAI. You can include the Maven dependency using the following configuration:

<dependency>
  <groupId>com.openai</groupId>
  <artifactId>openai-java</artifactId>
  <version>0.31.0</version>
</dependency>

A simple API request to Chat Completions would look like this:

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.ChatCompletion;
import com.openai.models.ChatCompletionCreateParams;
import com.openai.models.ChatModel;

// Create a custom client with AvalAI's base URL
OpenAIClient client = OpenAIOkHttpClient.builder()
  .baseUrl("https://api.avalai.ir/v1") // AvalAI API endpoint
  .apiKey(System.getenv("AVALAI_API_KEY"))
  .build();

ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
  .addUserMessage("Say this is a test")
  .model(ChatModel.O3_MINI)
  .build();
ChatCompletion chatCompletion = client.chat().completions().create(params);

Responses API version:

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

OpenAIClient client = OpenAIOkHttpClient.builder()
  .baseUrl("https://api.avalai.ir/v1") // AvalAI API endpoint
  .apiKey(System.getenv("AVALAI_API_KEY"))
  .build();

ResponseCreateParams params = ResponseCreateParams.builder()
  .input("Say this is a test")
  .model("gpt-5.6-luna")
  .build();

Response response = client.responses().create(params);
System.out.println(response.outputText());

Go

OpenAI provides an API helper for the Go programming language that can be used with AvalAI. You can import the library using the code below:

import (
	"github.com/openai/openai-go" // imported as openai
)

A simple API request to Chat Completions would look like this:

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/openai/openai-go"
	"github.com/openai/openai-go/option"
)

func main() {
	client := openai.NewClient(
		option.WithAPIKey(os.Getenv("AVALAI_API_KEY")),
		option.WithBaseURL("https://api.avalai.ir/v1"), // AvalAI API endpoint
	)
	chatCompletion, err := client.Chat.Completions.New(
		context.TODO(), openai.ChatCompletionNewParams{
			Messages: openai.F(
				[]openai.ChatCompletionMessageParamUnion{
					openai.UserMessage("Say this is a test"),
				},
			),
			Model: openai.F(openai.ChatModel("gpt-5.6-luna")),
		},
	)

	if err != nil {
		panic(err)
	}

	fmt.Println(chatCompletion.Choices[0].Message.Content)
}

Responses API version:

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/option"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient(
		option.WithAPIKey(os.Getenv("AVALAI_API_KEY")),
		option.WithBaseURL("https://api.avalai.ir/v1"), // AvalAI API endpoint
	)
	resp, err := client.Responses.New(context.TODO(), openai.ResponseNewParams{
		model: "gpt-5.6-luna",
		Input: responses.ResponseNewParamsInputUnion{
			OfString: openai.String("Say this is a test"),
		},
	})
	if err != nil {
		panic(err.Error())
	}

	fmt.Println(resp.OutputText())
}

Ruby

OpenAI provides an official Ruby SDK. Use it with AvalAI only when your installed SDK version supports a custom base URL; otherwise use the raw HTTP fallback in the CLI section.

Add the SDK to your application:

gem "openai"

Responses API version:

require "openai"

openai = OpenAI::Client.new(
  api_key: ENV.fetch("AVALAI_API_KEY"),
  base_url: "https://api.avalai.ir/v1"
)

response = openai.responses.create(
  model: "gpt-5.6-luna",
  input: "Write a one-sentence bedtime story about a unicorn."
)

puts(response.output_text)

OpenAI CLI

OpenAI's CLI is useful for repeatable terminal workflows, but it may target OpenAI's hosted API unless your installed version exposes a custom base URL setting. When your CLI supports OPENAI_BASE_URL, point it at AvalAI explicitly:

# If your installed openai CLI supports OPENAI_BASE_URL, point it at AvalAI.
OPENAI_API_KEY="$AVALAI_API_KEY" \
  OPENAI_BASE_URL="https://api.avalai.ir/v1" \
  openai responses create \
  --model gpt-5.5 \
  --input "Write a one-sentence bedtime story about a unicorn." \
  --format yaml \
  --transform 'output.#(type=="message").content.0.text'

Use --format, --transform, and YAML request bodies for repeatable scripts where you want the assistant text, JSON extraction, or one record per line for shell tools. Keep generated files such as project.json, .env, uploaded file IDs, and raw API responses out of Git, because CLI workflows often write secrets or customer data to disk.

If your CLI version does not honor OPENAI_BASE_URL, or you are testing a newly released AvalAI route before the CLI exposes flags for it, prefer raw HTTP because the endpoint and API key are explicit:

curl "https://api.avalai.ir/v1/responses" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-luna",
    "input": "Write a one-sentence bedtime story about a unicorn."
  }'

Use this fallback when testing new endpoints, debugging SDK behavior, or composing scripts with jq. If you use the generated openai CLI directly, run a harmless /v1/models or short /v1/responses check first to verify that AVALAI_API_KEY and the AvalAI base URL are actually being used.

Anthropic Official SDKs

AvalAI now supports Anthropic's official SDKs, allowing you to use native Anthropic client libraries with familiar syntax and features while accessing models through AvalAI's unified API system. As of June 2025, the Anthropic SDK can be used to access models from multiple providers, not just Claude models.

Multi-Provider Support

The Anthropic SDK can now be used to access chat models from:

• OpenAI
• Anthropic
• AWS Bedrock
• Vertex AI
• Gemini

Any chat model from these providers that supports the chat completion endpoint can be used through the Anthropic official SDK and the "v1/messages" endpoint in Anthropic's API schema.

Python

Install the official Anthropic Python SDK:

pip install anthropic

Configure the client to use AvalAI's endpoint:

import os
import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir",  # AvalAI API endpoint without /v1
)

# Using a Claude model
message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content)

# Using an OpenAI model through the Anthropic SDK
message = client.messages.create(
    model="gpt-5.6-luna",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, GPT-5.5!"}],
)
print(message.content)

# Using a Gemini model through the Anthropic SDK
message = client.messages.create(
    model="gemini-2.5-pro",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Gemini!"}],
)
print(message.content)

TypeScript/JavaScript

Install the official Anthropic TypeScript SDK:

npm install @anthropic-ai/sdk

Configure the client:

import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir", // AvalAI API endpoint without /v1
});

// Using a Claude model
const claudeMsg = await anthropic.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
});
console.log(claudeMsg);

// Using an OpenAI model through the Anthropic SDK
const openaiMsg = await anthropic.messages.create({
  model: "gpt-5.6-luna",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(openaiMsg);

// Using a Vertex AI model through the Anthropic SDK
const vertexMsg = await anthropic.messages.create({
  model: "gemini-2.5-pro",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Gemini!" }],
});
console.log(vertexMsg);

Go

Install the official Anthropic Go SDK:

go get github.com/anthropics/anthropic-sdk-go

Configure the client:

package main

import (
	"context"
	"fmt"
	"github.com/anthropics/anthropic-sdk-go"
	"github.com/anthropics/anthropic-sdk-go/option"
	"os"
)

func main() {
	client := anthropic.NewClient(
		option.WithAPIKey(os.Getenv("AVALAI_API_KEY")),
		option.WithBaseURL("https://api.avalai.ir"), // AvalAI endpoint without /v1
	)

	message, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
		Model:     anthropic.F(anthropic.ModelClaudeSonnet4_0),
		MaxTokens: anthropic.F(int64(1024)),
		Messages: anthropic.F([]anthropic.MessageParam{
			anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude")),
		}),
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", message.Content)
}

Ruby

Install the official Anthropic Ruby gem:

gem install anthropic

Configure the client:

require "bundler/setup"
require "anthropic"

anthropic = Anthropic::Client.new(
    api_key: ENV.fetch("AVALAI_API_KEY"),
    base_url: "https://api.avalai.ir" # AvalAI endpoint without /v1
)

message = anthropic.messages.create(
    max_tokens: 1024,
    messages: [{
        role: "user",
        content: "Hello, Claude"
    }],
    model: "claude-sonnet-5"
)

puts(message.content)

Beta Features

All Anthropic SDKs support beta namespace for experimental features:

import os
import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir",  # AvalAI API endpoint without /v1
)

message = client.beta.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    betas=["beta-feature-name"],
)
print(message.content)

Available Models

When using Anthropic SDKs with AvalAI, you can access models from multiple providers:

Claude Models

• Claude Opus 4.7 - claude-opus-4-7
• Claude Sonnet 4.6 - claude-sonnet-4-6
• Claude Sonnet 4.5 - claude-sonnet-4-5
• Claude Haiku 4.5 - claude-haiku-4-5

Other Provider Models

You can also access models from:

• OpenAI (e.g., gpt-5.5, gpt-5.3-codex, gpt-5-mini)
• AWS Bedrock models
• Vertex AI models
• Gemini (e.g., gemini-3.5-flash, gemini-3.1-pro-preview)

For a complete list, see our Models documentation.

Google GenAI SDK

AvalAI now supports Google's official GenAI SDK for native access to Gemini models using Google's native API schema and endpoints.

JavaScript/TypeScript

Install the Google GenAI SDK:

npm install @google/genai

Configure the client to use AvalAI's endpoint:

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
	apiKey: process.env.AVALAI_API_KEY,
	httpOptions: {"apiVersion": "v1beta", "baseUrl": "https://api.avalai.ir"}
});

async function main() {
	const response = await ai.models.generateContent({
		model: "gemini-2.5-flash",
		contents: "Write a brief summary of key machine learning principles.",
	});
	console.log(response.text);
}

await main();

Python

Install the Google GenAI SDK:

pip install google-generativeai

Configure the client to use AvalAI's endpoint:

import os
from google import genai
from google.genai.types import ContentDict, PartDict

# Initialize client with AvalAI endpoint
client = genai.Client(
    api_key=os.environ["AVALAI_API_KEY"],
    http_options={"base_url": "https://api.avalai.ir"},  # Note: no /v1 suffix
)

# Generate content using native API
contents = ContentDict(
    parts=[PartDict(text="Write a short story about AI")], role="user"
)

response = await client.agenerate_content(
    contents=contents, model="gemini-2.5-flash", max_tokens=500
)

print(response)

Streaming Support

# Streaming generation
response = await client.agenerate_content_stream(
    contents=contents, model="gemini-2.5-flash", max_tokens=500
)

async for chunk in response:
    print(chunk)

Key Features

• Native API Schema: Direct access using Google's generateContent and streamGenerateContent endpoints
• Flexible Authentication: Support for both Authorization: Bearer and x-goog-api-key headers
• Full Streaming Support: Native streaming capabilities
• Multimodal Support: Native support for text, image, audio, and video inputs

Important Limitations

• Gemini Models Only: This SDK exclusively supports Gemini models
• Base URL: Use https://api.avalai.ir (without /v1) when configuring the SDK
• v1beta Endpoints: Uses /v1beta/models/{model}:generateContent endpoint format

For complete documentation, see the v1beta API Reference.

Azure OpenAI libraries

Microsoft's Azure team maintains libraries that are compatible with both the OpenAI API and Azure OpenAI services. These libraries can also be configured to work with AvalAI by specifying the custom endpoint. Read the library documentation below to learn how you can use them with the AvalAI API.

• Azure OpenAI client library for .NET
• Azure OpenAI client library for JavaScript
• Azure OpenAI client library for Java
• Azure OpenAI client library for Go

Community libraries

The libraries below are built and maintained by the broader developer community for use with OpenAI's API. Many of these can be configured to work with AvalAI by specifying the base URL as https://api.avalai.ir/v1. You can also watch OpenAI's OpenAPI specification repository on GitHub to get timely updates on when there are changes to the API.

Please note that AvalAI does not verify the correctness or security of these projects. Use them at your own risk!

C# / .NET

• Betalgo.OpenAI by Betalgo
• OpenAI-API-dotnet by OkGoDoIt
• OpenAI-DotNet by RageAgainstThePixel

C++

• liboai by D7EAD

Clojure

• openai-clojure by wkok

Crystal

• openai-crystal by sferik

Dart/Flutter

• openai by anasfik

Delphi

• DelphiOpenAI by HemulGM

Elixir

• openai.ex by mgallo

Go

• go-gpt3 by sashabaranov

Java

• simple-openai by Sashir Estela
• Spring AI

Julia

• OpenAI.jl by rory-linehan

Kotlin

• openai-kotlin by Mouaad Aallam

Node.js

• openai-api by Njerschow
• openai-api-node by erlapso
• gpt-x by ceifa
• gpt3 by poteat
• gpts by thencc
• @dalenguyen/openai by dalenguyen
• tectalic/openai by tectalic

PHP

• orhanerday/open-ai by orhanerday
• tectalic/openai by tectalic
• openai-php client by openai-php

Python

• chronology by OthersideAI

R

• rgpt3 by ben-aaron188

Ruby

• openai by nileshtrivedi
• ruby-openai by alexrudall

Rust

• async-openai by 64bit
• fieri by lbkolev

Scala

• openai-scala-client by cequence-io

Swift

• AIProxySwift by Lou Zell
• OpenAIKit by dylanshine
• OpenAI by MacPaw

Unity

• OpenAi-Api-Unity by hexthedev
• com.openai.unity by RageAgainstThePixel

Unreal Engine

• OpenAI-Api-Unreal by KellanM

Other useful repositories

• tiktoken - counting tokens
• simple-evals - simple evaluation library
• mle-bench - library to evaluate machine learning engineer agents
• gym - reinforcement learning library
• swarm - educational orchestration repository

Related Resources

• API Reference
• Authentication
• Quickstart