DurenAI API

Integrate AI characters into your applications with our powerful and flexible API

API Access by Plan

Free

STARTER
No API Access

Upgrade to Standard or higher for API access

RECOMMENDED

Standard

$14.99/mo
Basic API Access
150 requests/minute
No Webhook Support

Premium

$24.99/mo
Full API Access
750 requests/minute
Webhook Integration

Enterprise

CUSTOM
Custom API Solutions
Custom Rate Limits
Dedicated Support

Introduction

The DurenAI API allows you to integrate AI characters into your applications. With our API, you can:

  • Access thousands of pre-built AI characters
  • Create and customize your own AI characters
  • Generate chat responses from characters
  • Manage user interactions and conversations
  • Retrieve character information and metadata

Our API is designed to be easy to use, reliable, and scalable. We offer different access levels based on your subscription plan.

API Access Requirements

API access is available on Standard plans and above. Free tier users do not have API access. See our pricing page for more details.

Base URL

https://api.durenai.com/v1

All API requests should be made to this base URL, followed by the specific endpoint.

Authentication

To use the DurenAI API, you'll need an API key. You can get one by signing up for a Standard or higher plan.

Include your API key in the headers of all requests using the X-API-Key header:

curl -X GET "https://api.durenai.com/v1/characters" \
-H "X-API-Key: your_api_key_here"

Security Warning

Never expose your API key in client-side code. Always make API requests from your server to protect your API key.

Rate Limits

To ensure fair usage and system stability, we apply rate limits to API requests. Rate limits vary based on your subscription plan.

PlanRate LimitChat RequestsAPI Access Level
FreeNo API access500 per monthNone
StandardRECOMMENDED150 requests per minute7,500 per monthBasic API
Premium750 requests per minute25,000 per monthFull API
EnterpriseCustomCustomCustom API

Rate limit information is included in the response headers:

X-RateLimit-Limit: 150
X-RateLimit-Remaining: 149
X-RateLimit-Reset: 1620000000

If you exceed your rate limit, you'll receive a 429 Too Many Requests response.

Endpoints

Characters

GET
/characters
Standard+

Retrieve a list of available characters. Results are paginated and can be filtered by various parameters.

Parameters

NameTypeRequiredDescription
pageinteger
Optional
Page number for pagination. Default is 1.
limitinteger
Optional
Number of results per page. Default is 20, maximum is 100.
tagsstring
Optional
Filter by tags, comma-separated (e.g., 'fantasy,female').
sortstring
Optional
Sort results by: 'popular', 'trending', 'newest'. Default is 'popular'.

Examples

Response
{
"data": [
  {
    "id": "char_123456",
    "name": "Vexa Stride",
    "description": "A mysterious rogue courier with the ability to navigate the cyberpunk underworld.",
    "tags": ["cyberpunk", "female", "fictional"],
    "image_url": "https://api.durenai.com/images/vexa-stride.jpg",
    "created_at": "2023-05-15T10:30:00Z",
    "likes": 1243,
    "chat_count": 8721
  },
  {
    "id": "char_789012",
    "name": "Axel Blaze",
    "description": "A former firefighter who gained pyrokinetic abilities after a freak accident.",
    "tags": ["superhero", "male", "fictional"],
    "image_url": "https://api.durenai.com/images/axel-blaze.jpg",
    "created_at": "2023-06-22T14:15:00Z",
    "likes": 958,
    "chat_count": 6542
  }
],
"pagination": {
  "total": 2500,
  "page": 1,
  "limit": 20,
  "pages": 125
}
}
Code Samples
Python
example.py
import requests

api_key = "your_api_key_here"
headers = {
  "X-API-Key": api_key
}

response = requests.get(
  "https://api.durenai.com/v1/characters",
  headers=headers,
  params={
      "page": 1,
      "limit": 20,
      "tags": "cyberpunk,female",
      "sort": "popular"
  }
)

if response.status_code == 200:
  characters = response.json()
  for character in characters["data"]:
      print(f"{character['name']}: {character['description']}")
else:
  print(f"Error: {response.status_code}")
  print(response.text)
Node.js
example.js
const axios = require('axios');

const apiKey = 'your_api_key_here';

async function getCharacters() {
try {
  const response = await axios.get('https://api.durenai.com/v1/characters', {
    headers: {
      'X-API-Key': apiKey
    },
    params: {
      page: 1,
      limit: 20,
      tags: 'cyberpunk,female',
      sort: 'popular'
    }
  });
  
  const characters = response.data;
  characters.data.forEach(character => {
    console.log(`${character.name}: ${character.description}`);
  });
  
} catch (error) {
  console.error('Error fetching characters:', error.response ? error.response.data : error.message);
}
}

getCharacters();
GET
/characters/{character_id}
Standard+

Retrieve detailed information about a specific character.

Parameters

NameTypeRequiredDescription
character_idstring
Required
The unique identifier of the character.

Examples

Response
{
"id": "char_123456",
"name": "Vexa Stride",
"description": "A mysterious rogue courier with the ability to navigate the cyberpunk underworld.",
"personality": "Defiant, quick-witted, and fiercely independent. Vexa thrives on adrenaline and the freedom of movement.",
"background": "Raised in the sprawling megacity slums, Vexa learned to survive by becoming the fastest courier in the neon-lit underworld.",
"tags": ["cyberpunk", "female", "fictional", "limitless"],
"image_url": "https://api.durenai.com/images/vexa-stride.jpg",
"created_at": "2023-05-15T10:30:00Z",
"creator": {
  "id": "user_789012",
  "username": "owenarii"
},
"stats": {
  "likes": 1243,
  "chat_count": 8721,
  "followers": 952
}
}
POST
/characters
Premium+

Create a new character.

Parameters

NameTypeRequiredDescription
namestring
Required
The name of the character.
descriptionstring
Required
A short description of the character.
personalitystring
Required
The character's personality traits.
backgroundstring
Required
The character's background story.
tagsarray
Optional
Array of tags to categorize the character.
imagefile
Optional
Character image file (JPEG or PNG, max 5MB).

Examples

Request
{
"name": "Nova Chen",
"description": "A tech genius who developed an AI that can predict future events with startling accuracy.",
"personality": "Innovative, socially awkward, and intensely focused. Nova sees patterns where others see chaos.",
"background": "Child prodigy who built her first supercomputer at age 12, now leading the world's most advanced predictive technology company.",
"tags": ["sci-fi", "female", "genius"]
}
Response
{
"id": "char_345678",
"name": "Nova Chen",
"description": "A tech genius who developed an AI that can predict future events with startling accuracy.",
"personality": "Innovative, socially awkward, and intensely focused. Nova sees patterns where others see chaos.",
"background": "Child prodigy who built her first supercomputer at age 12, now leading the world's most advanced predictive technology company.",
"tags": ["sci-fi", "female", "genius"],
"image_url": null,
"created_at": "2023-07-18T09:45:00Z",
"creator": {
  "id": "user_123456",
  "username": "current_user"
},
"stats": {
  "likes": 0,
  "chat_count": 0,
  "followers": 0
}
}

Chat

POST
/chat/{character_id}/messages
Standard+

Send a message to a character and get a response.

Parameters

NameTypeRequiredDescription
character_idstring
Required
The unique identifier of the character.
messagestring
Required
The message to send to the character.
conversation_idstring
Optional
ID of an existing conversation. If not provided, a new conversation will be created.

Examples

Request
{
"message": "Tell me about your adventures as a courier."
}
Response
{
"id": "msg_123456",
"conversation_id": "conv_789012",
"character_id": "char_123456",
"content": "Well, let me tell you about the time I had to outrun a corporate security drone swarm while delivering a package to the underground resistance. I was zooming through the neon-lit streets of Neo-Tokyo on my hacked hoverboard, pushing it to speeds it was never designed for. The drones were relentless, but I know every shortcut and hidden passage in this city. I ducked into an abandoned subway tunnel, cut through the old shopping district, and finally lost them by skimming across the water reservoir. The client was impressed—said most couriers would have ditched the package at the first sign of trouble. But that's not how I work. What else do you want to know about life in the fast lane?",
"created_at": "2023-07-20T15:30:00Z",
"is_character": true
}
Code Samples
Python
example.py
import requests

api_key = "your_api_key_here"
headers = {
  "X-API-Key": api_key,
  "Content-Type": "application/json"
}

character_id = "char_123456"
conversation_id = "conv_789012"  # Optional, remove if starting a new conversation

data = {
  "message": "Tell me about your adventures as a courier.",
  "conversation_id": conversation_id  # Remove this line if starting a new conversation
}

response = requests.post(
  f"https://api.durenai.com/v1/chat/{character_id}/messages",
  headers=headers,
  json=data
)

if response.status_code == 200:
  result = response.json()
  print(f"Character response: {result['content']}")
else:
  print(f"Error: {response.status_code}")
  print(response.text)
Node.js
example.js
const axios = require('axios');

const apiKey = 'your_api_key_here';
const characterId = 'char_123456';
const conversationId = 'conv_789012';  // Optional, remove if starting a new conversation

async function sendMessage() {
try {
  const response = await axios.post(
    `https://api.durenai.com/v1/chat/${characterId}/messages`,
    {
      message: 'Tell me about your adventures as a courier.',
      conversation_id: conversationId  // Remove this line if starting a new conversation
    },
    {
      headers: {
        'X-API-Key': apiKey,
        'Content-Type': 'application/json'
      }
    }
  );
  
  console.log('Character response:', response.data.content);
  
} catch (error) {
  console.error('Error sending message:', error.response ? error.response.data : error.message);
}
}

sendMessage();
GET
/chat/conversations
Standard+

Retrieve a list of the user's conversations.

Parameters

NameTypeRequiredDescription
pageinteger
Optional
Page number for pagination. Default is 1.
limitinteger
Optional
Number of results per page. Default is 20, maximum is 50.

Examples

Response
{
"data": [
  {
    "id": "conv_789012",
    "character": {
      "id": "char_123456",
      "name": "Vexa Stride",
      "image_url": "https://api.durenai.com/images/vexa-stride.jpg"
    },
    "last_message": {
      "content": "Well, let me tell you about the time I had to outrun a corporate security drone swarm...",
      "created_at": "2023-07-20T15:30:00Z",
      "is_character": true
    },
    "created_at": "2023-07-20T15:25:00Z",
    "updated_at": "2023-07-20T15:30:00Z",
    "message_count": 2
  },
  {
    "id": "conv_345678",
    "character": {
      "id": "char_789012",
      "name": "Axel Blaze",
      "image_url": "https://api.durenai.com/images/axel-blaze.jpg"
    },
    "last_message": {
      "content": "The fire doesn't control me, I control it. That's the first lesson I had to learn...",
      "created_at": "2023-07-19T10:15:00Z",
      "is_character": true
    },
    "created_at": "2023-07-19T10:10:00Z",
    "updated_at": "2023-07-19T10:15:00Z",
    "message_count": 3
  }
],
"pagination": {
  "total": 12,
  "page": 1,
  "limit": 20,
  "pages": 1
}
}
GET
/chat/conversations/{conversation_id}/messages
Standard+

Retrieve messages from a specific conversation.

Parameters

NameTypeRequiredDescription
conversation_idstring
Required
The unique identifier of the conversation.
pageinteger
Optional
Page number for pagination. Default is 1.
limitinteger
Optional
Number of results per page. Default is 20, maximum is 100.

Examples

Response
{
"data": [
  {
    "id": "msg_123456",
    "conversation_id": "conv_789012",
    "character_id": "char_123456",
    "content": "Well, let me tell you about the time I had to outrun a corporate security drone swarm while delivering a package to the underground resistance...",
    "created_at": "2023-07-20T15:30:00Z",
    "is_character": true
  },
  {
    "id": "msg_123455",
    "conversation_id": "conv_789012",
    "character_id": null,
    "content": "Tell me about your adventures as a courier.",
    "created_at": "2023-07-20T15:25:00Z",
    "is_character": false
  }
],
"pagination": {
  "total": 2,
  "page": 1,
  "limit": 20,
  "pages": 1
}
}

User

GET
/user/me
Standard+

Retrieve information about the authenticated user.

Examples

Response
{
"id": "user_123456",
"username": "current_user",
"email": "user@example.com",
"created_at": "2023-01-15T08:30:00Z",
"subscription": {
  "plan": "standard",
  "status": "active",
  "chat_requests": {
    "used": 2450,
    "limit": 7500,
    "reset_date": "2023-08-01T00:00:00Z"
  }
},
"stats": {
  "characters_created": 8,
  "conversations": 24,
  "favorites": 12
}
}
GET
/user/favorites
Standard+

Retrieve a list of the user's favorite characters.

Parameters

NameTypeRequiredDescription
pageinteger
Optional
Page number for pagination. Default is 1.
limitinteger
Optional
Number of results per page. Default is 20, maximum is 50.

Examples

Response
{
"data": [
  {
    "id": "char_123456",
    "name": "Vexa Stride",
    "description": "A mysterious rogue courier with the ability to navigate the cyberpunk underworld.",
    "tags": ["cyberpunk", "female", "fictional"],
    "image_url": "https://api.durenai.com/images/vexa-stride.jpg",
    "created_at": "2023-05-15T10:30:00Z",
    "favorited_at": "2023-06-10T14:25:00Z"
  },
  {
    "id": "char_789012",
    "name": "Axel Blaze",
    "description": "A former firefighter who gained pyrokinetic abilities after a freak accident.",
    "tags": ["superhero", "male", "fictional"],
    "image_url": "https://api.durenai.com/images/axel-blaze.jpg",
    "created_at": "2023-06-22T14:15:00Z",
    "favorited_at": "2023-06-25T09:10:00Z"
  }
],
"pagination": {
  "total": 8,
  "page": 1,
  "limit": 20,
  "pages": 1
}
}
POST
/user/favorites/{character_id}
Standard+

Add a character to the user's favorites.

Parameters

NameTypeRequiredDescription
character_idstring
Required
The unique identifier of the character to favorite.

Examples

Response
{
"success": true,
"message": "Character added to favorites",
"character_id": "char_123456",
"favorited_at": "2023-07-21T11:30:00Z"
}
DELETE
/user/favorites/{character_id}
Standard+

Remove a character from the user's favorites.

Parameters

NameTypeRequiredDescription
character_idstring
Required
The unique identifier of the character to unfavorite.

Examples

Response
{
"success": true,
"message": "Character removed from favorites",
"character_id": "char_123456"
}

Webhooks

PREMIUM+

Premium Feature

Webhook functionality is available exclusively for Premium ($24.99/mo) and Enterprise plans.Upgrade your plan to access these features.

POST
/webhooks
Premium+

Create a new webhook subscription.

Parameters

NameTypeRequiredDescription
urlstring
Required
The URL that will receive webhook events.
eventsarray
Required
Array of event types to subscribe to (e.g., 'message.created', 'character.updated').
descriptionstring
Optional
Optional description for this webhook.

Examples

Request
{
"url": "https://example.com/webhook-handler",
"events": ["message.created", "conversation.updated"],
"description": "Notification webhook for chat events"
}
Response
{
"id": "webhook_123456",
"url": "https://example.com/webhook-handler",
"events": ["message.created", "conversation.updated"],
"description": "Notification webhook for chat events",
"created_at": "2023-07-21T11:30:00Z",
"status": "active",
"secret": "whsec_abcdefghijklmnopqrstuvwxyz" 
}

Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of a request. In general:

  • 2xx indicates success
  • 4xx indicates an error that failed given the information provided (e.g., a required parameter was omitted)
  • 5xx indicates an error with our servers

Error Response Format

All error responses follow a consistent format:

{
"error": {
  "code": "invalid_request",
  "message": "A detailed error message",
  "status": 400,
  "details": {
    // Additional error details, if available
  }
}
}

Common Error Codes

Status CodeError CodeDescription
400invalid_requestThe request was malformed or contained invalid parameters.
401unauthorizedNo valid API key was provided.
403forbiddenThe API key doesn't have permissions to perform the request.
403subscription_requiredThis endpoint requires a Standard or higher subscription plan.
403premium_requiredThis endpoint requires a Premium or Enterprise subscription plan.
404not_foundThe requested resource doesn't exist.
429rate_limitedToo many requests hit the API too quickly.
500server_errorSomething went wrong on our end.

Error Handling Example

import requests

api_key = "your_api_key_here"
headers = {
  "X-API-Key": api_key
}

try:
  response = requests.get(
      "https://api.durenai.com/v1/characters/invalid_id",
      headers=headers
  )
  
  response.raise_for_status()  # Raises an exception for 4xx/5xx responses
  character = response.json()
  
except requests.exceptions.HTTPError as e:
  error_response = e.response.json()
  print(f"Error {error_response['error']['status']}: {error_response['error']['message']}")
  
except Exception as e:
  print(f"An unexpected error occurred: {str(e)}")

SDKs & Libraries

We provide official client libraries for several popular programming languages to make integrating with our API even easier.

Python

Our Python SDK provides a simple interface to interact with the DurenAI API.

pip install durenai
View Documentation →

JavaScript

Our JavaScript SDK works in both Node.js and browser environments.

npm install durenai-js
View Documentation →

Community Libraries

Our community has developed libraries for additional languages:

Pricing & Limits

Our API is available on Standard plans and above. Below is a summary of the API features available in each plan.

FeatureFreeStandard
($14.99/mo)
Premium
($24.99/mo)
Enterprise
API AccessBasic APIFull APICustom API
Rate Limits150 req/min750 req/minCustom
Character Creation API
Webhook Support
API SupportStandardPriorityDedicated

Need More API Capacity?

If you need higher rate limits or custom API features, our Enterprise plan offers tailored solutions for your specific requirements.

Enterprise API Solutions

Our Enterprise plan offers custom API solutions tailored to your organization's specific needs. Contact our sales team to discuss your requirements.

Enterprise API Features

  • Custom rate limits tailored to your usage patterns
  • Dedicated API infrastructure for improved reliability
  • Custom endpoints for specific business requirements
  • Advanced analytics and reporting capabilities
  • Service Level Agreements (SLAs) with guaranteed uptime
  • Technical account manager for ongoing support

Request Enterprise Info

Ready to Start Building?

Integrate AI characters into your applications today with our powerful and flexible API

HomeCharactersCreateChatsLogin/Sign Up