Quickstart: Integrate the AI Girlfriend API

Base URL and Authentication

Our API follows the OpenAI chat-completions standard, making integration straightforward for existing clients. You must include your API key in the Authorization header of every request. The base URL for all endpoints is https://api.roleplayapi.com/v1. When using official SDKs, update the base_url configuration to point to this address and provide your key as the api_key. This setup ensures your requests reach our dedicated uncensored endpoint without modification to your standard logic.

Send a Completion

Initiate a conversation by sending a POST request to /v1/chat/completions. The model identifier is uncensored. You can pass any number of messages in the messages array to establish context or start a fresh dialogue. The response contains the model's text output, which you can stream or parse as a JSON object. This endpoint handles the core text-in, text-out interaction required for character-driven apps.

Copycurl https://api.roleplayapi.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Write a blunt product review of a cheap VPN."}]
  }'

Python SDK Integration

Use the official openai Python library to interact with the API with minimal boilerplate. Configure the client with our base URL and your API key. Then, call chat.completions.create with the uncensored model ID. This approach leverages existing type hints and error handling mechanisms, allowing you to focus on your application logic rather than HTTP parsing. The response object provides access to the generated content directly.

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.roleplayapi.com/v1", api_key="YOUR_KEY")

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Summarise this thread without softening it."}],
)
print(resp.choices[0].message.content)

Node SDK Integration

For JavaScript and TypeScript projects, the OpenAI Node SDK provides a clean interface for API calls. Initialize the client with the custom base URL and your secret key. Invoke the chat completions endpoint using the uncensored model. This method is ideal for web servers or edge functions where you need to manage asynchronous requests efficiently. The SDK handles serialization and deserialization of the JSON payload automatically.

Copyimport OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.roleplayapi.com/v1", apiKey: process.env.API_KEY });

const resp = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "Draft a villain monologue for my game." }],
});
console.log(resp.choices[0].message.content);

Enable Streaming

Reduce perceived latency by enabling server-sent events (SSE). Set the stream parameter to true in your request. The API will return a stream of chunks instead of a single complete response. This is particularly useful for chat interfaces where users expect immediate character responses. You can process each chunk as it arrives, updating the UI incrementally. The stream ends when the model finishes generating the token sequence.

Copystream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Tell the story in second person."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Limits, Errors, and Context

Your requests are subject to a rate limit of 300 requests per minute per key. If you exceed this, the API returns a 429 status code. Authentication failures result in a 401 error, while insufficient prepaid credit triggers a 402 error. The context window supports up to 100,000 tokens for the combined prompt and completion. If you need to check available models, send a GET request to /v1/models. Ensure your request body does not exceed 8 MB.