Product

Selcora API Reference

Integrate AI characters, conversations, and image generation into your applications

Authentication

All API requests require authentication using an API key. Include your API key in the request headers using Bearer authentication:

headers.js

1// API Key Header
2{
3  "Authorization": "Bearer your_api_key_here"
4}

Getting your API key

You can find your API key in your account settings under the API section. Keep this key secret and don't expose it in client-side code.

Rate Limiting

API requests are rate-limited based on your plan:

Plan	Limit
Free	5 requests per minute
Pro	100 requests per minute

Rate limit information is included in response headers: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Models API

Use the Models API to retrieve available language models (LLMs) or stable diffusion models (SD).

GET List Models

models_list.jsGET

1GET /api/v1/models?type=llm
2
3// Response
4[
5  {
6    "id": "model_abc123",
7    "name": "GPT-4",
8    "max_context": 8192,
9    "cost_per_1k_tokens": 0.06
10  },
11  {
12    "id": "model_def456",
13    "name": "Claude 3 Opus",
14    "max_context": 100000,
15    "cost_per_1k_tokens": 0.15
16  }
17]

Parameters

Name	Type	Description
type	string	The type of models to retrieve. Required Available values: `llm`, `sd`

Available Models

Language Models (LLM)

No LLM models available.

Stable Diffusion Models (SD)

No SD models available.

Completions API

The Completions API lets you generate responses from a language model.

POST Generate Completion

completions.jsPOST

1POST /api/v1/completions
2
3// Request
4{
5  "messages": [
6    {
7      "role": "system",
8      "content": "You are a helpful assistant."
9    },
10    {
11      "role": "user",
12      "content": "Tell me about AI."
13    }
14  ],
15  "llm_id": "model_abc123",
16  "agent_id": "agent_xyz789" // [Optional] Agent to use for the completion
17}
18
19// Response
20{
21  "id": "msg_789xyz",
22  "content": "AI, or artificial intelligence, refers to systems or machines that mimic human intelligence...",
23  "role": "agent",
24  "created_at": "2023-09-01T12:00:00Z"
25}

Request Body

Name	Type	Description
messages	array	An array of message objects. Each message must have `role` and `content`. Required
llm_id	string	The ID of the language model to use. Required
agent_id	string	The ID of an agent to use for the completion. Optional

Notes

The first message can be a 'system' message to set context
The last message must be from the 'user'
Sufficient account balance is required for the request to succeed

Conversations API

Manage ongoing conversations with language models.

GET List Conversations

conversations_list.jsGET

1GET /api/v1/conversations
2
3// Response
4[
5  {
6    "id": "conv_123abc",
7    "title": "AI Discussion",
8    "system_prompt": "You are a helpful assistant.",
9    "llm_id": "model_abc123",
10    "last_message_at": "2023-09-01T12:00:00Z",
11    "agent_id": "agent_xyz789"
12  }
13]

POST Create Conversation

conversations_create.jsPOST

1POST /api/v1/conversations
2
3// Request
4{
5  "title": "New Discussion",
6  "system_prompt": "You are a helpful assistant.",
7  "llm_id": "model_abc123",
8  "agent_id": "agent_xyz789", // [Optional] Agent to associate with conversation
9  "messages": [] // [Optional] Initial messages for the conversation
10}
11
12// Response
13{
14  "id": "conv_123abc",
15  "title": "New Discussion",
16  "system_prompt": "You are a helpful assistant.",
17  "llm_id": "model_abc123",
18  "last_message_at": "2023-09-01T12:00:00Z",
19  "agent_id": "agent_xyz789"
20}

GET Get Conversation

conversations_get.jsGET

1GET /api/v1/conversations/{id}
2
3// Response
4{
5  "id": "conv_123abc",
6  "title": "AI Discussion",
7  "system_prompt": "You are a helpful assistant.",
8  "llm_id": "model_abc123",
9  "last_message_at": "2023-09-01T12:00:00Z",
10  "agent_id": "agent_xyz789"
11}

Messages API

Manage messages within a conversation.

GET List Messages

messages_list.jsGET

1GET /api/v1/conversations/{conversation_id}/messages
2
3// Response
4[
5  {
6    "id": "msg_123abc",
7    "content": "Hello, how can I help you today?",
8    "role": "agent",
9    "created_at": "2023-09-01T12:00:00Z"
10  },
11  {
12    "id": "msg_456def",
13    "content": "I'd like to learn about AI.",
14    "role": "user",
15    "created_at": "2023-09-01T12:01:00Z"
16  }
17]

POST Create Message

messages_create.jsPOST

1POST /api/v1/conversations/{conversation_id}/messages
2
3// Request
4{
5  "content": "Tell me about neural networks.",
6  "llm_id": "model_abc123", // [Optional] LLM to use (defaults to conversation's LLM)
7  "verbose": true // [Optional] Include thought process in response
8}
9
10// Response
11{
12  "id": "msg_789xyz",
13  "content": "Neural networks are computational models inspired by the human brain...",
14  "role": "agent",
15  "created_at": "2023-09-01T12:05:00Z"
16}

Notes

Creating a message automatically generates a response from the agent/LLM
The endpoint creates two messages: your user message and the AI's response
Sufficient account balance is required for the request to succeed

Agents API

Manage AI agents with customizable appearances and personalities.

GET List Agents

agents_list.jsGET

1GET /api/v1/agents
2
3// Response
4[
5  {
6    "id": "agent_xyz789",
7    "name": "Technical Advisor",
8    "appearance_prompt": "Professional, wearing glasses",
9    "personality_prompt": "Helpful and technically proficient",
10    "description": "A technical expert who can help with coding questions"
11  }
12]

POST Create Agent

agents_create.jsPOST

1POST /api/v1/agents
2
3// Request
4{
5  "name": "Financial Advisor",
6  "appearance_prompt": "Professional, suit and tie",
7  "personality_prompt": "Knowledgeable about finance, patient",
8  "description": "An agent specialized in financial advice",
9  "sd_model_id": "sd_model_456abc",
10  "age": 35
11}
12
13// Response
14{
15  "id": "agent_789abc",
16  "name": "Financial Advisor",
17  "appearance_prompt": "35 years old, Professional, suit and tie",
18  "personality_prompt": "Knowledgeable about finance, patient",
19  "description": "An agent specialized in financial advice",
20  "avatar_url": "https://example.com/images/agent_789abc.png"
21}

Request Body

Name	Type	Description
name	string	Name of the agent. Required
appearance_prompt	string	Description of the agent's appearance for image generation.
personality_prompt	string	Description of the agent's personality.
description	string	General description of the agent's purpose.
sd_model_id	string	ID of the stable diffusion model to use for generating the agent's avatar. Required
age	number	Age of the agent (must be 18 or older). Optional

Notes

When sd_model_id is provided, the response will include an avatar_url field with the generated image.
When the age parameter Optional is provided, it will be prepended to the appearance prompt.
Appearance and personality prompts are screened for prohibited content.

GET Get Agent

agents_get.jsGET

1GET /api/v1/agents/{id}
2
3// Response
4{
5  "id": "agent_xyz789",
6  "name": "Technical Advisor",
7  "appearance_prompt": "Professional, wearing glasses",
8  "personality_prompt": "Helpful and technically proficient",
9  "description": "A technical expert who can help with coding questions"
10}

Images API

Generate and retrieve AI-created images.

GET List Images

images_list.jsGET

1GET /api/v1/images?page=1&page_size=10
2
3// Response
4{
5  "data": [
6    {
7      "id": "img_123abc",
8      "prompt": "A futuristic city with flying cars",
9      "url": "https://example.com/images/img_123abc.png",
10      "created_at": "2023-09-01T12:00:00Z"
11    }
12  ],
13  "pagination": {
14    "total_items": 25,
15    "current_page": 1,
16    "page_size": 10,
17    "total_pages": 3,
18    "next_page": 2,
19    "prev_page": null
20  }
21}

POST Generate Image

images_generate.jsPOST

1POST /api/v1/images
2
3// Request
4{
5  "prompt": "A serene beach at sunset with palm trees",
6  "sd_model_id": "sd_model_456abc",
7  "conversation_id": "conv_123abc" // [Optional] Link image to this conversation
8}
9
10// Response
11{
12  "id": "img_789xyz",
13  "prompt": "A serene beach at sunset with palm trees",
14  "url": "https://example.com/images/img_789xyz.png",
15  "created_at": "2023-09-01T12:10:00Z"
16}

Request Body

Name	Type	Description
prompt	string	Description of the image to generate. Required
sd_model_id	string	The ID of the stable diffusion model to use. Required
conversation_id	string	Link the image to a conversation. Optional

Notes

When a conversation_id is provided, the system will automatically insert the generated image into the conversation thread as a message with no text content, just an image.

Error Handling

The API uses standard HTTP status codes to indicate success or failure of requests:

error_handling.js

1// Success (200, 201)
2{
3  "id": "resource_id",
4  "name": "Resource Name",
5  // Other resource properties
6}
7
8// Client Error (400, 401, 402, 404)
9{
10  "error": "Detailed error message explaining what went wrong"
11}
12
13// Server Error (500)
14{
15  "error": "Internal error"
16}

Common Status Codes

Code	Description
200 OK	Request succeeded
201 Created	Resource successfully created
400 Bad Request	Invalid parameters or request format
402 Payment Required	Insufficient account balance
404 Not Found	Resource not found
500 Internal Server Error	Server-side error