Get Started with OpenAI-Compatible APIs

When integrating with any new API, especially one designed to be compatible with OpenAI's ecosystem, the fastest path to confirmation is not to immediately wire it into a full application. Instead, start with a single, minimal request. This approach allows you to quickly verify the fundamental components: the base URL, the authentication mechanism (API key), the model name, and the expected response structure. Once this basic call is working, you can confidently integrate it into your larger product. This article provides a straightforward workflow for this initial testing phase, leveraging common development tools.

To streamline this process, a compact examples repository has been assembled. It is designed for that exact first-call workflow, ensuring you can get a working example running in minutes. The repository includes ready-to-use examples for curl, Python, and Node.js, covering both standard and streaming responses, as well as JSON structured output. It also provides helpful migration notes and a small error reference guide.

Environment Variables: Best Practice for Credentials

The first critical step in setting up your API calls is to manage your credentials securely. Keeping sensitive information like API keys directly in your source code is a significant security risk. The industry standard and recommended practice is to use environment variables. This separates your configuration from your codebase, making it easier to manage different environments (development, staging, production) and preventing accidental exposure of secrets.

For these examples, you will need to set at least two environment variables:

ORIGINSTARTAI_API_KEY=your_api_key_here
ORIGINSTARTAI_BASE_URL=your_base_url_here

Replace your_api_key_here with your actual API key provided by the service. Similarly, your_base_url_here should be replaced with the specific endpoint URL for the OpenAI-compatible API you are targeting. This setup ensures that your code can access these values without hardcoding them.

Making Your First Call with cURL

cURL is a ubiquitous command-line tool for transferring data with URLs, making it an excellent choice for quick API testing. The following command demonstrates how to make a simple completion request:

curl -X POST \
  <YOUR_BASE_URL>/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{ 
    "model": "gpt-3.5-turbo", 
    "messages": [{"role": "user", "content": "Say this is a test!"}], 
    "temperature": 0.7 
  }'

In this command:

  • -X POST specifies the HTTP method.
  • <YOUR_BASE_URL>/v1/chat/completions is the endpoint for chat completions, using your configured base URL.
  • -H "Content-Type: application/json" sets the request header to indicate JSON data.
  • -H "Authorization: Bearer <YOUR_API_KEY>" provides your API key for authentication.
  • -d '...' contains the JSON payload, specifying the model, messages, and other parameters like temperature.

You can adapt this command to test different models or prompts. The response will be a JSON object containing the model's reply.

Python Example: Programmatic API Interaction

Python's requests library makes making HTTP requests straightforward. Here’s how you can replicate the cURL call in Python:

import os
import requests

api_key = os.getenv("ORIGINSTARTAI_API_KEY")
base_url = os.getenv("ORIGINSTARTAI_BASE_URL")

if not api_key or not base_url:
    print("Please set ORIGINSTARTAI_API_KEY and ORIGINSTARTAI_BASE_URL environment variables.")
    exit()

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {api_key}"
}

payload = {
    "model": "gpt-3.5-turbo",
    "messages": [
        {
            "role": "user",
            "content": "Say this is a test!"
        }
    ],
    "temperature": 0.7
}

url = f"{base_url}/v1/chat/completions"

response = requests.post(url, headers=headers, json=payload)

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error: {response.status_code}")
    print(response.text)

This script retrieves the API key and base URL from environment variables, constructs the request headers and payload, and sends a POST request to the chat completions endpoint. It then prints the JSON response or an error message if the request fails.

Node.js Example: Asynchronous API Interaction

For Node.js developers, the built-in https module or popular libraries like axios can be used. Here's an example using axios, which is common in the Node.js ecosystem:

const axios = require('axios');

const apiKey = process.env.ORIGINSTARTAI_API_KEY;
const baseUrl = process.env.ORIGINSTARTAI_BASE_URL;

if (!apiKey || !baseUrl) {
  console.error("Please set ORIGINSTARTAI_API_KEY and ORIGINSTARTAI_BASE_URL environment variables.");
  process.exit(1);
}

const headers = {
  'Content-Type': 'application/json',
  'Authorization': `Bearer ${apiKey}`
};

const payload = {
  model: "gpt-3.5-turbo",
  messages: [
    {
      role: "user",
      content: "Say this is a test!"
    }
  ],
  temperature: 0.7
};

const url = `${baseUrl}/v1/chat/completions`;

axios.post(url, payload, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(`Error: ${error.response.status}`);
    console.error(error.response.data);
  });

This Node.js script, assuming you have axios installed (npm install axios), performs the same action. It reads credentials from environment variables, defines the request body, and sends an asynchronous POST request. The .then() block handles a successful response, logging the data, while the .catch() block logs any errors encountered during the request.

Handling Streaming Responses

For applications requiring real-time text generation, streaming responses are essential. This allows the API to send back chunks of text as they are generated, rather than waiting for the entire response to be complete. Both cURL, Python, and Node.js can handle this, though the implementation differs.

With cURL, you can use the --no-buffer option to see the stream as it arrives. For Python and Node.js, you'll typically need to set the stream: true parameter in your request and handle the response as a stream of data.

The repository linked earlier contains specific examples for handling streaming responses, which involves iterating over incoming data chunks and processing them as they arrive. This is crucial for building interactive chat interfaces or real-time content generation tools.

Next Steps and Further Considerations

Once you have a working basic API call, the next steps involve integrating this functionality into your application. Consider error handling more robustly, managing rate limits, and potentially exploring advanced features like function calling or JSON mode if the API supports them.

The examples provided serve as a foundational block. The true power comes from understanding how to adapt these basic calls to fit the specific requirements of your project. Always refer to the documentation of the specific OpenAI-compatible API you are using for details on available models, parameters, and any unique features.