How to Use APIVAI as an OpenAI-Compatible API Gateway

Introduction

Many developer tools, command-line utilities, and AI applications support OpenAI-compatible endpoints. APIVAI provides a gateway-style API experience that lets developers test and integrate AI models through familiar request patterns without rewriting every client from scratch.

This guide focuses on practical integration details: OpenAI-compatible request structure, /v1/models, /v1/chat/completions, API key authentication, Python, Node.js, cURL examples, streaming responses, and configuration notes for Claude Code and Cursor.

What is an OpenAI-compatible API gateway?

An OpenAI-compatible API gateway exposes request and response patterns that are familiar to developers who have used OpenAI-style APIs. The most important pieces are a base URL, Bearer token authentication, JSON request bodies, a model field, a messages array, response choices, and optional streaming.

For APIVAI, the default OpenAI-compatible base URL is:

https://api.apivai.com/v1

Compatibility can vary by client and feature. Treat the gateway as a developer-friendly integration layer, then test the specific models, parameters, and tools your application depends on.

When should developers use APIVAI?

Use APIVAI when you want to test OpenAI-compatible request flows, connect local scripts, try Python, Node.js, or cURL examples, configure tools that support custom OpenAI-compatible base URLs, or check model availability before hardcoding model names.

It is also useful when you want a cost-effective API gateway for development workflows while keeping your application code close to standard OpenAI-compatible patterns.

Basic environment variables

For macOS and Linux:

export APIVAI_API_KEY="YOUR_APIVAI_API_KEY"
export APIVAI_BASE_URL="https://api.apivai.com/v1"
export APIVAI_MODEL="YOUR_MODEL_NAME"

For PowerShell:

$env:APIVAI_API_KEY="YOUR_APIVAI_API_KEY"
$env:APIVAI_BASE_URL="https://api.apivai.com/v1"
$env:APIVAI_MODEL="YOUR_MODEL_NAME"

Keep your API key outside source control. Use environment variables, a local secret manager, or your deployment platform's secret store.

Discover available models

Before hardcoding a model name, call /v1/models and inspect the response. This helps avoid configuration drift when a client, model alias, or provider-side availability changes.

curl "$APIVAI_BASE_URL/models" \
  -H "Authorization: Bearer $APIVAI_API_KEY"

A typical response includes a data array. Choose a model ID from that list and set it as APIVAI_MODEL.

Send a chat completion with cURL

curl "$APIVAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $APIVAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$APIVAI_MODEL"'",
    "messages": [
      { "role": "system", "content": "You are a concise developer assistant." },
      { "role": "user", "content": "Explain API gateway routing in one paragraph." }
    ]
  }'

If the request succeeds, read choices[0].message.content from the JSON response.

Python example

The OpenAI Python SDK can be pointed at APIVAI by changing the base_url.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["APIVAI_API_KEY"],
    base_url=os.environ.get("APIVAI_BASE_URL", "https://api.apivai.com/v1"),
)

response = client.chat.completions.create(
    model=os.environ["APIVAI_MODEL"],
    messages=[
        {"role": "system", "content": "You write clear developer documentation."},
        {"role": "user", "content": "Give me a short API gateway checklist."},
    ],
)

print(response.choices[0].message.content)

Node.js example

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.APIVAI_API_KEY,
  baseURL: process.env.APIVAI_BASE_URL || "https://api.apivai.com/v1",
});

const response = await client.chat.completions.create({
  model: process.env.APIVAI_MODEL,
  messages: [
    { role: "system", content: "You are a practical coding assistant." },
    { role: "user", content: "Write a small JSON API testing checklist." },
  ],
});

console.log(response.choices[0].message.content);

Streaming example

Streaming is useful for CLIs, chat interfaces, and tools that should display tokens as they arrive. Enable stream: true and iterate over chunks.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["APIVAI_API_KEY"],
    base_url=os.environ.get("APIVAI_BASE_URL", "https://api.apivai.com/v1"),
)

stream = client.chat.completions.create(
    model=os.environ["APIVAI_MODEL"],
    messages=[{"role": "user", "content": "Stream three API debugging tips."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Claude Code configuration notes

Claude Code primarily expects Anthropic-style configuration. Some gateway setups expose Claude-compatible routes separately from OpenAI-compatible routes, so verify the current APIVAI dashboard or documentation before assuming a single base URL works for every client.

For Claude Code, the common pattern is to set an auth token and base URL for the CLI, then run a small test prompt:

export ANTHROPIC_AUTH_TOKEN="YOUR_APIVAI_API_KEY"
export ANTHROPIC_BASE_URL="https://api.apivai.com"
claude

If your Claude Code version changes its provider configuration format, prefer the official client configuration mechanism and keep APIVAI as the custom endpoint.

Cursor configuration notes

Cursor and similar editors may allow a custom OpenAI-compatible base URL. Use:

https://api.apivai.com/v1

Then set your APIVAI API key in the tool's API key field and choose a model that appears in /v1/models. If a specific model does not appear in the editor UI, test it first with cURL or a small script before relying on it in daily coding work.

Troubleshooting

If you receive 401 Unauthorized, check that the Authorization header is exactly Bearer YOUR_APIVAI_API_KEY, the key has not been pasted with spaces, and the environment variable is loaded in the shell running your script.

If you receive 404 Not Found, confirm that your base URL includes /v1 for OpenAI-compatible calls and that the path is /chat/completions or /models.

If you receive a model error, call /v1/models again and copy the exact model ID from the response. Avoid guessing model names from older examples.

If streaming does not render in your tool, test the same request without stream: true. Some clients buffer streamed output or require a separate streaming parser.

If a third-party tool behaves differently from your script, compare the exact base URL, headers, model name, and JSON body. Small differences such as a missing /v1 or an unsupported parameter can change the result.

Integration checklist

Start with /v1/models, choose a model ID, run a non-streaming /v1/chat/completions request, add streaming only after the basic request works, and then configure your editor or CLI.

This approach keeps the first integration small and observable. Once the request path, authentication, and model selection are working, you can move the same pattern into a larger application.