Integrate AI characters into your applications with our powerful and flexible API
Upgrade to Standard or higher for API access
The DurenAI API allows you to integrate AI characters into your applications. With our API, you can:
Our API is designed to be easy to use, reliable, and scalable. We offer different access levels based on your subscription plan.
API access is available on Standard plans and above. Free tier users do not have API access. See our pricing page for more details.
https://api.durenai.com/v1All API requests should be made to this base URL, followed by the specific endpoint.
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"Never expose your API key in client-side code. Always make API requests from your server to protect your API key.
To ensure fair usage and system stability, we apply rate limits to API requests. Rate limits vary based on your subscription plan.
| Plan | Rate Limit | Chat Requests | API Access Level |
|---|---|---|---|
| Free | No API access | 500 per month | None |
| StandardRECOMMENDED | 150 requests per minute | 7,500 per month | Basic API |
| Premium | 750 requests per minute | 25,000 per month | Full API |
| Enterprise | Custom | Custom | Custom API |
Rate limit information is included in the response headers:
X-RateLimit-Limit: 150
X-RateLimit-Remaining: 149
X-RateLimit-Reset: 1620000000If you exceed your rate limit, you'll receive a 429 Too Many Requests response.
/charactersRetrieve a list of available characters. Results are paginated and can be filtered by various parameters.
| Name | Type | Required | Description |
|---|---|---|---|
| page | integer | Optional | Page number for pagination. Default is 1. |
| limit | integer | Optional | Number of results per page. Default is 20, maximum is 100. |
| tags | string | Optional | Filter by tags, comma-separated (e.g., 'fantasy,female'). |
| sort | string | Optional | Sort results by: 'popular', 'trending', 'newest'. Default is 'popular'. |
{
"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
}
}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)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();/characters/{character_id}Retrieve detailed information about a specific character.
| Name | Type | Required | Description |
|---|---|---|---|
| character_id | string | Required | The unique identifier of the character. |
{
"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
}
}/charactersCreate a new character.
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Required | The name of the character. |
| description | string | Required | A short description of the character. |
| personality | string | Required | The character's personality traits. |
| background | string | Required | The character's background story. |
| tags | array | Optional | Array of tags to categorize the character. |
| image | file | Optional | Character image file (JPEG or PNG, max 5MB). |
{
"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"]
}{
"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/{character_id}/messagesSend a message to a character and get a response.
| Name | Type | Required | Description |
|---|---|---|---|
| character_id | string | Required | The unique identifier of the character. |
| message | string | Required | The message to send to the character. |
| conversation_id | string | Optional | ID of an existing conversation. If not provided, a new conversation will be created. |
{
"message": "Tell me about your adventures as a courier."
}{
"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
}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)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();/chat/conversationsRetrieve a list of the user's conversations.
| Name | Type | Required | Description |
|---|---|---|---|
| page | integer | Optional | Page number for pagination. Default is 1. |
| limit | integer | Optional | Number of results per page. Default is 20, maximum is 50. |
{
"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
}
}/chat/conversations/{conversation_id}/messagesRetrieve messages from a specific conversation.
| Name | Type | Required | Description |
|---|---|---|---|
| conversation_id | string | Required | The unique identifier of the conversation. |
| page | integer | Optional | Page number for pagination. Default is 1. |
| limit | integer | Optional | Number of results per page. Default is 20, maximum is 100. |
{
"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/meRetrieve information about the authenticated user.
{
"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
}
}/user/favoritesRetrieve a list of the user's favorite characters.
| Name | Type | Required | Description |
|---|---|---|---|
| page | integer | Optional | Page number for pagination. Default is 1. |
| limit | integer | Optional | Number of results per page. Default is 20, maximum is 50. |
{
"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
}
}/user/favorites/{character_id}Add a character to the user's favorites.
| Name | Type | Required | Description |
|---|---|---|---|
| character_id | string | Required | The unique identifier of the character to favorite. |
{
"success": true,
"message": "Character added to favorites",
"character_id": "char_123456",
"favorited_at": "2023-07-21T11:30:00Z"
}/user/favorites/{character_id}Remove a character from the user's favorites.
| Name | Type | Required | Description |
|---|---|---|---|
| character_id | string | Required | The unique identifier of the character to unfavorite. |
{
"success": true,
"message": "Character removed from favorites",
"character_id": "char_123456"
}Webhook functionality is available exclusively for Premium ($24.99/mo) and Enterprise plans.Upgrade your plan to access these features.
/webhooksCreate a new webhook subscription.
| Name | Type | Required | Description |
|---|---|---|---|
| url | string | Required | The URL that will receive webhook events. |
| events | array | Required | Array of event types to subscribe to (e.g., 'message.created', 'character.updated'). |
| description | string | Optional | Optional description for this webhook. |
{
"url": "https://example.com/webhook-handler",
"events": ["message.created", "conversation.updated"],
"description": "Notification webhook for chat events"
}{
"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"
}The API uses conventional HTTP response codes to indicate the success or failure of a request. In general:
All error responses follow a consistent format:
{
"error": {
"code": "invalid_request",
"message": "A detailed error message",
"status": 400,
"details": {
// Additional error details, if available
}
}
}| Status Code | Error Code | Description |
|---|---|---|
| 400 | invalid_request | The request was malformed or contained invalid parameters. |
| 401 | unauthorized | No valid API key was provided. |
| 403 | forbidden | The API key doesn't have permissions to perform the request. |
| 403 | subscription_required | This endpoint requires a Standard or higher subscription plan. |
| 403 | premium_required | This endpoint requires a Premium or Enterprise subscription plan. |
| 404 | not_found | The requested resource doesn't exist. |
| 429 | rate_limited | Too many requests hit the API too quickly. |
| 500 | server_error | Something went wrong on our end. |
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)}")We provide official client libraries for several popular programming languages to make integrating with our API even easier.
Our Python SDK provides a simple interface to interact with the DurenAI API.
pip install durenaiOur JavaScript SDK works in both Node.js and browser environments.
npm install durenai-jsOur community has developed libraries for additional languages:
Our API is available on Standard plans and above. Below is a summary of the API features available in each plan.
| Feature | Free | Standard ($14.99/mo) | Premium ($24.99/mo) | Enterprise |
|---|---|---|---|---|
| API Access | Basic API | Full API | Custom API | |
| Rate Limits | 150 req/min | 750 req/min | Custom | |
| Character Creation API | ||||
| Webhook Support | ||||
| API Support | Standard | Priority | Dedicated |
If you need higher rate limits or custom API features, our Enterprise plan offers tailored solutions for your specific requirements.
Our Enterprise plan offers custom API solutions tailored to your organization's specific needs. Contact our sales team to discuss your requirements.
Integrate AI characters into your applications today with our powerful and flexible API