API Reference

The API uses standard HTTP status codes to indicate the success or failure of a request. All endpoints require a valid API key provided in the Authorization header.

POST/v1/chat

Handles general chat interactions. This endpoint is optimized for high-volume conversational AI applications, providing state-of-the-art responses with low latency across our global edge network.

Parameters

promptstring, required

The user's chat message or instruction.

modelstring, required

The identifier of the specific model that processed this request (e.g., Spark, Forge, Void).

personalitystring, optional

An optional personality for the assistant to adopt during the conversation.

Response Body Explanation

id: A unique identifier for this specific API request starting with Rit_.
model: The identifier of the specific model that processed this request.
output: The main generated response from the AI.
usage: Insights into the token consumption (input, output, and total).

cURL Request

curl https://api.ravonixapi.com/v1/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "prompt": "Hello, how are you?",
    "model": "Spark",
    "personality": "friendly"
  }'

Successful Response

{
  "id": "Rit_f827d66ef341d6ad4afa3aeb",
  "model": "Spark",
  "output": "I am an AI assistant, and I'm here to help you. How can I assist you today?",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 25,
    "total_tokens": 37
  }
}

POST/v1/assistant

Acts as a server assistant for various tasks. Designed for technical queries, command generation, and administrative automation.

Parameters

promptstring, required

The user's query or command for the assistant.

modelstring, required

The model to use for the assistant.

personalitystring, optional

An optional personality for the assistant (e.g., 'helpful', 'concise').

Response Body Explanation

id: A unique identifier for this specific API request starting with Rit_.
model: The identifier of the specific model that processed this request.
output: The main generated response from the AI.
usage: Insights into the token consumption (input, output, and total).

cURL Request

curl https://api.ravonixapi.com/v1/assistant \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "prompt": "How do I restart the server?",
    "model": "Forge",
    "personality": "helpful"
  }'

Successful Response

{
  "id": "Rit_a1b2c3d4e5f6g7h8i9j0k1l2",
  "model": "Forge",
  "output": "To restart the server, you typically need to access the server's command line or control panel and issue a 'restart' command. For Linux, 'sudo reboot' is common.",
  "usage": {
    "input_tokens": 15,
    "output_tokens": 40,
    "total_tokens": 55
  }
}

POST/v1/npc

Generates NPC (Non-Player Character) dialogue and logic. Optimized for gaming environments where character consistency and immersion are paramount.

Parameters

promptstring, required

The interaction context or player message.

modelstring, required

The model to use for the chat.

personalitystring, required

The specific personality profile of the NPC (e.g., 'gruff blacksmith').

Response Body Explanation

id: A unique identifier for this specific API request starting with Rit_.
model: The identifier of the specific model that processed this request.
output: The main generated response from the AI.
usage: Insights into the token consumption (input, output, and total).

cURL Request

curl https://api.ravonixapi.com/v1/npc \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "prompt": "Tell me about the blacksmith in this town.",
    "model": "Spark",
    "personality": "gruff"
  }'

Successful Response

{
  "id": "Rit_z9y8x7w6v5u4t3s2r1q0p9o8",
  "model": "Spark",
  "output": "Old man Grognak, he's been forging steel here for decades. Keeps to himself mostly, but his work is solid.",
  "usage": {
    "input_tokens": 14,
    "output_tokens": 35,
    "total_tokens": 49
  }
}

POST/v1/roleplay

Engages in roleplay scenarios. This endpoint uses high-intelligence models to maintain complex narrative states and deep character immersion.

Parameters

promptstring, required

The roleplay action or dialogue.

modelstring, required

The model to use for the chat.

personalitystring, optional

A talkative pirate captain or any detailed persona.

Response Body Explanation

id: A unique identifier for this specific API request starting with Rit_.
model: The identifier of the specific model that processed this request.
output: The main generated response from the AI.
usage: Insights into the token consumption (input, output, and total).

cURL Request

curl https://api.ravonixapi.com/v1/roleplay \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "prompt": "You are a pirate. Greet me.",
    "model": "Forge",
    "personality": "A talkative pirate captain."
  }'

Successful Response

{
  "id": "Rit_m1n2o3p4q5r6s7t8u9v0w1x2",
  "model": "Forge",
  "output": "Ahoy there, matey! What brings ye to these here shores? Speak yer mind or walk the plank!",
  "usage": {
    "input_tokens": 18,
    "output_tokens": 28,
    "total_tokens": 46
  }
}

POST/v1/quest

Generates a quest for a game or story. Uses reasoning-heavy models to create logically sound and engaging objectives.

Parameters

promptstring, required

The theme or setting for the quest.

modelstring, required

The model to use for quest generation (Void recommended).

personalitystring, optional

An optional personality for the quest generator (e.g., 'mysterious').

Response Body Explanation

id: A unique identifier for this specific API request starting with Rit_.
model: The identifier of the specific model that processed this request.
output: The main generated response from the AI.
usage: Insights into the token consumption (input, output, and total).

cURL Request

curl https://api.ravonixapi.com/v1/quest \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "prompt": "Create a quest to retrieve a lost artifact from a haunted forest.",
    "model": "Void",
    "personality": "mysterious"
  }'

Successful Response

{
  "id": "Rit_b2c3d4e5f6g7h8i9j0k1l2m3",
  "model": "Void",
  "output": "A whispered legend speaks of the 'Moonpetal Amulet,' lost in the Whispering Woods. Recover it from the ancient guardian...",
  "usage": {
    "input_tokens": 25,
    "output_tokens": 45,
    "total_tokens": 70
  }
}

Error Reference

400

Bad Request

Reason: Missing required field (e.g., prompt, model) or invalid JSON format.

Solution

Ensure all required fields are included and the JSON syntax is valid.

{
  "error": {
    "code": 400,
    "message": "Bad Request",
    "reason": "Missing required field (e.g., prompt, model) or invalid JSON format."
  }
}

401

Unauthorized

Reason: The API key is missing, invalid, or revoked.

Solution

Provide a valid API key in the Authorization header.

{
  "error": {
    "code": 401,
    "message": "Unauthorized",
    "reason": "The API key is missing, invalid, or revoked."
  }
}

402

Payment Required

Reason: Your monthly token balance has been fully consumed.

Solution

Upgrade your plan or wait until your next billing cycle.

{
  "error": {
    "code": 402,
    "message": "Payment Required",
    "reason": "Your monthly token balance has been fully consumed."
  }
}

403

Forbidden

Reason: The model or feature is not available on your current plan.

Solution

Upgrade your plan or choose a model available in your tier.

{
  "error": {
    "code": 403,
    "message": "Forbidden",
    "reason": "The model or feature is not available on your current plan."
  }
}

404

Not Found

Reason: The requested endpoint does not exist.

Solution

Check the endpoint path and spelling. Example: /v1/chat.

{
  "error": {
    "code": 404,
    "message": "Not Found",
    "reason": "The requested endpoint does not exist."
  }
}

429

Too Many Requests

Reason: You exceeded your plan’s RPM or TPM limits.

Solution

Reduce request frequency or upgrade your plan for higher limits.

{
  "error": {
    "code": 429,
    "message": "Too Many Requests",
    "reason": "You exceeded your plan’s RPM or TPM limits."
  }
}

500

Internal Server Error

Reason: An unexpected error occurred while processing the request.

Solution

Retry the request later. If the issue continues, contact support.

{
  "error": {
    "code": 500,
    "message": "Internal Server Error",
    "reason": "An unexpected error occurred while processing the request."
  }
}