Openai - Kigma Docs

OpenAI API Reference Documentation

This document provides an overview of the OpenAI API, its functionality, and how to interact with it.

Introduction

The OpenAI API allows interaction with OpenAI's powerful language models through HTTP requests. You can utilize the API from any programming language, leveraging our official libraries for Python and Node.js, or other community-maintained libraries.

Installation:

Python: pip install openai
Node.js: npm install openai

Authentication

The OpenAI API uses API keys for authentication, which can be created at either the user or service account level.

Project Keys: These are preferred for security reasons, as they provide access only to a specific project.
User Keys: These are legacy keys that provide access to all organizations and projects associated with the user. It's highly recommended to transition to project keys.

Never expose your API key in client-side code! Production requests should be routed through your backend server, securely loading the key from an environment variable or a key management service.

Authorization Header: Include your API key in every request using the following header:

Authorization: Bearer OPENAI_API_KEY

Organizations and Projects (Optional):

If you belong to multiple organizations or access projects with a user key, you can specify the desired organization and project for an API request using headers:

OpenAI-Organization: Your organization ID
OpenAI-Project: Your project ID

You can find these IDs in your OpenAI account settings.

Making Requests

Here's an example of a basic API request using curl:

curl https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
     "model": "gpt-4o-mini",
     "messages": [{"role": "user", "content": "Say this is a test!"}],
     "temperature": 0.7
   }'

This requests the gpt-4o-mini model to complete the prompt "Say this is a test!". The response will be a JSON object containing the generated text and other information.

Streaming

Streaming enables receiving partial responses for certain requests, providing real-time updates as the model generates content. This is supported for Chat Completions and the Assistants API.

Streaming in Python:

from openai import OpenAI
 
client = OpenAI()
 
stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Say this is a test"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")

Streaming in Node/Typescript:

import OpenAI from "openai";
 
const openai = new OpenAI();
 
async function main() {
    const stream = await openai.chat.completions.create({
        model: "gpt-4o-mini",
        messages: [{ role: "user", "content: "Say this is a test" }],
        stream: true,
    });
    for await (const chunk of stream) {
        process.stdout.write(chunk.choices[0]?.delta?.content || "");
    }
}
 
main();

Parsing Server-Sent Events:

Parsing these events requires careful handling. It's recommended to use existing client libraries to avoid parsing errors.

Debugging Requests

Apart from error codes in API responses, HTTP headers can be inspected for debugging purposes. These headers contain information like the request ID and rate limiting details.

Key Headers:

openai-organization: Organization associated with the request
openai-processing-ms: Request processing time
openai-version: REST API version used
x-request-id: Unique identifier for the request
Rate limiting information (e.g., x-ratelimit-limit-requests)

Logging x-request-id is recommended for production deployments.

Accessing Raw Response Objects:

If you're using OpenAI's SDKs, you'll need specific methods to access raw response objects and headers. Refer to the SDK documentation for details.

API Endpoints

The OpenAI API offers a variety of endpoints for different functionalities:

Audio: Transcribe and translate audio, and create speech from text. Chat: Generate responses in a conversational format. Embeddings: Obtain vector representations of text inputs. Fine-tuning: Customize models by training them on your data. Batch: Asynchronously process large batches of API requests. Files: Upload and manage files for use with other endpoints. Uploads: Upload large files in multiple parts. Images: Generate and edit images based on text prompts. Models: List and retrieve information about available models. Moderations: Classify text for potential harm. Assistants: Create and manage AI assistants that can perform tasks. Threads: Manage threads for assistants to interact with. Messages: Create and manage messages within threads. Runs: Execute runs on threads using assistants. Run Steps: Manage individual steps in run executions. Vector Stores: Manage vector stores for storing data for the file_search tool. Vector Store Files: Manage files within vector stores. Vector Store File Batches: Manage batches of files being added to vector stores. Administration: Manage your organization, including invites, users, projects, and audit logs. Legacy: Includes legacy endpoints for Completions and Assistants (v1).

Gemini Groq