API Reference

The Ravonix API is engineered for the Minecraft Ecosystem. Use standard HTTP status codes and provide your API key in the Authorization header.

POST/v1/chat

Optimized for general Minecraft assistant queries, technical Paper/Spigot help, and player support interactions.

Parameters

promptstring, required

The user's query or instruction.

modelstring, required

Spark, Forge, or Void.

temperaturefloat, optional

Controls randomness (0.0 to 2.0). Lower is more focused, higher is more creative. Default: 0.7.

max_tokensinteger, optional

The maximum length of the generated response. Default: 1000.

personalitystring, optional

An optional persona for the AI to adopt (e.g., 'A talkative pirate').

top_pfloat, optional

Nucleus sampling. Default: 1.0.

stopstring/array, optional

Sequences where the API will stop generating further tokens.

ninteger, optional

Number of choices to generate. Default: 1.

Response Schema

id: Unique identifier for the request (starts with Rit_).
model: The Ravonix model used.
output: The AI generated text.
usage: input_tokens, output_tokens, and total_tokens.

cURL Request

curl https://api.ravonixapi.com/v1/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "Forge",
    "prompt": "How do I optimize my server.properties for 100 players?",
    "temperature": 0.5
  }'

Successful Response

{
  "id": "Rit_cc2e9577f360560be36a3a6d",
  "model": "Forge",
  "output": "To optimize for 100 players, set view-distance=6, network-compression-threshold=256, and ensure your RAM allocation is...",
  "usage": { "input_tokens": 15, "output_tokens": 45, "total_tokens": 60 }
}

POST/v1/assistant

A game-aware technical assistant designed for server automation, command generation, and plugin logic analysis.

Parameters

promptstring, required

The command or logic query.

modelstring, required

Forge or Void recommended.

temperaturefloat, optional

Controls randomness (0.0 to 2.0). Lower is more focused, higher is more creative. Default: 0.7.

max_tokensinteger, optional

The maximum length of the generated response. Default: 1000.

personalitystring, optional

An optional persona for the AI to adopt (e.g., 'A talkative pirate').

top_pfloat, optional

Nucleus sampling. Default: 1.0.

stopstring/array, optional

Sequences where the API will stop generating further tokens.

ninteger, optional

Number of choices to generate. Default: 1.

Response Schema

id: Unique identifier for the request (starts with Rit_).
model: The Ravonix model used.
output: The AI generated text.
usage: input_tokens, output_tokens, and total_tokens.

cURL Request

curl https://api.ravonixapi.com/v1/assistant \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "Void",
    "prompt": "Write a complex /execute command to summon particles around players with Diamond Armor.",
    "max_tokens": 200
  }'

Successful Response

{
  "id": "Rit_a1b2c3d4e5f6g7h8i9j0k1l2",
  "model": "Void",
  "output": "/execute as @a[nbt={Inventory:[{Slot:102b,id:\"minecraft:diamond_chestplate\"}]}] run particle soul_fire_flame ~ ~ ~ 0.5 1 0.5 0.01 10",
  "usage": { "input_tokens": 22, "output_tokens": 35, "total_tokens": 57 }
}

POST/v1/npc

Generates immersive NPC dialogue for in-game characters. Ensures character consistency within the Minecraft universe.

Parameters

promptstring, required

The player interaction or context.

modelstring, required

Spark or Forge.

temperaturefloat, optional

Controls randomness (0.0 to 2.0). Lower is more focused, higher is more creative. Default: 0.7.

max_tokensinteger, optional

The maximum length of the generated response. Default: 1000.

personalitystring, optional

An optional persona for the AI to adopt (e.g., 'A talkative pirate').

top_pfloat, optional

Nucleus sampling. Default: 1.0.

stopstring/array, optional

Sequences where the API will stop generating further tokens.

ninteger, optional

Number of choices to generate. Default: 1.

Response Schema

id: Unique identifier for the request (starts with Rit_).
model: The Ravonix model used.
output: The AI generated text.
usage: input_tokens, output_tokens, and total_tokens.

cURL Request

curl https://api.ravonixapi.com/v1/npc \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "Spark",
    "prompt": "I found something glowing in the deep dark.",
    "personality": "A terrified miner",
    "stop": ["."]
  }'

Successful Response

{
  "id": "Rit_f827d66ef341d6ad4afa3aeb",
  "model": "Spark",
  "output": "Don't touch it! The Wardens hear everything down there...",
  "usage": { "input_tokens": 18, "output_tokens": 12, "total_tokens": 30 }
}

POST/v1/roleplay

Engages in multi-turn roleplay. Supports system personas and conversation history for deep narrative immersion.

Parameters

messagesarray, required

List of message objects (role & content).

modelstring, required

Spark, Forge, or Void.

temperaturefloat, optional

Controls randomness (0.0 to 2.0). Lower is more focused, higher is more creative. Default: 0.7.

max_tokensinteger, optional

The maximum length of the generated response. Default: 1000.

personalitystring, optional

An optional persona for the AI to adopt (e.g., 'A talkative pirate').

top_pfloat, optional

Nucleus sampling. Default: 1.0.

stopstring/array, optional

Sequences where the API will stop generating further tokens.

ninteger, optional

Number of choices to generate. Default: 1.

Response Schema

id: Unique identifier for the request (starts with Rit_).
model: The Ravonix model used.
output: The AI generated text.
usage: input_tokens, output_tokens, and total_tokens.

cURL Request

curl https://api.ravonixapi.com/v1/roleplay \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "Forge",
    "messages": [
      { "role": "system", "content": "You are the King of Ravonix." },
      { "role": "user", "content": "The creepers have breached the outer wall!" }
    ],
    "temperature": 1.2
  }'

Successful Response

{
  "id": "Rit_cc2e9577f360560be36a3a6d",
  "model": "Forge",
  "output": "To arms! Gather the knights and fortify the keep. No explosive beast shall take our crown today!",
  "usage": { "input_tokens": 40, "output_tokens": 25, "total_tokens": 65 }
}

POST/v1/quest

Generates logically sound and narratively rich Minecraft quests, objectives, and rewards.

Parameters

promptstring, required

Quest theme or setting.

modelstring, required

Void recommended.

temperaturefloat, optional

Controls randomness (0.0 to 2.0). Lower is more focused, higher is more creative. Default: 0.7.

max_tokensinteger, optional

The maximum length of the generated response. Default: 1000.

personalitystring, optional

An optional persona for the AI to adopt (e.g., 'A talkative pirate').

top_pfloat, optional

Nucleus sampling. Default: 1.0.

stopstring/array, optional

Sequences where the API will stop generating further tokens.

ninteger, optional

Number of choices to generate. Default: 1.

Response Schema

id: Unique identifier for the request (starts with Rit_).
model: The Ravonix model used.
output: The AI generated text.
usage: input_tokens, output_tokens, and total_tokens.

cURL Request

curl https://api.ravonixapi.com/v1/quest \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "Void",
    "prompt": "A quest to find the lost library in a jungle biome.",
    "n": 1
  }'

Successful Response

{
  "id": "Rit_cc2e9577f360560be36a3a6d",
  "model": "Void",
  "output": "Quest: The Emerald Archives. Objective: Find the ruined temple at X: 450, Z: -1200. Reward: 1 Enchanted Golden Apple.",
  "usage": { "input_tokens": 20, "output_tokens": 40, "total_tokens": 60 }
}

POST/v1/lore

Generates deep historical myths and legends for the Minecraft universe. Ideal for world-building.

Parameters

promptstring, required

The topic of the lore (e.g., 'The origin of the Endermen').

modelstring, required

Forge or Void recommended.

temperaturefloat, optional

Controls randomness (0.0 to 2.0). Lower is more focused, higher is more creative. Default: 0.7.

max_tokensinteger, optional

The maximum length of the generated response. Default: 1000.

personalitystring, optional

An optional persona for the AI to adopt (e.g., 'A talkative pirate').

top_pfloat, optional

Nucleus sampling. Default: 1.0.

stopstring/array, optional

Sequences where the API will stop generating further tokens.

ninteger, optional

Number of choices to generate. Default: 1.

Response Schema

id: Unique identifier for the request (starts with Rit_).
model: The Ravonix model used.
output: The AI generated text.
usage: input_tokens, output_tokens, and total_tokens.

cURL Request

curl https://api.ravonixapi.com/v1/lore \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "Forge",
    "prompt": "Tell me the legend of the ancient guardians in the ocean monuments."
  }'

Successful Response

{
  "id": "Rit_cc2e9577f360560be36a3a6d",
  "model": "Forge",
  "output": "Long ago, before the oceans rose, a cult of aquatic warriors built grand palaces. To protect their treasures, they infused stone with life, creating the laser-eyed Guardians that remain to this day...",
  "usage": { "input_tokens": 25, "output_tokens": 75, "total_tokens": 100 }
}

POST/v1/custom

Direct bypass mode. Executes your instructions with 100% precision without any Ravonix system interference.

Parameters

promptstring, required

Your direct instructions.

modelstring, required

Any model.

temperaturefloat, optional

Controls randomness (0.0 to 2.0). Lower is more focused, higher is more creative. Default: 0.7.

max_tokensinteger, optional

The maximum length of the generated response. Default: 1000.

personalitystring, optional

An optional persona for the AI to adopt (e.g., 'A talkative pirate').

top_pfloat, optional

Nucleus sampling. Default: 1.0.

stopstring/array, optional

Sequences where the API will stop generating further tokens.

ninteger, optional

Number of choices to generate. Default: 1.

Response Schema

id: Unique identifier for the request (starts with Rit_).
model: The Ravonix model used.
output: The AI generated text.
usage: input_tokens, output_tokens, and total_tokens.

cURL Request

curl https://api.ravonixapi.com/v1/custom \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "Spark",
    "prompt": "Say exactly: SYSTEM_READY_V2"
  }'

Successful Response

{
  "id": "Rit_cc2e9577f360560be36a3a6d",
  "model": "Spark",
  "output": "SYSTEM_READY_V2",
  "usage": { "input_tokens": 10, "output_tokens": 5, "total_tokens": 15 }
}

Error Reference

Every error response includes a solution field to help you resolve issues immediately.

400

Bad Request

Reason

Missing required field or invalid JSON format.

Solution

Check your parameters and JSON syntax.

JSON Error Payload

{
  "error": {
    "code": 400,
    "message": "Bad Request",
    "reason": "Missing required field or invalid JSON format.",
    "solution": "Check your parameters and JSON syntax."
  }
}

401

Unauthorized

Reason

API key is missing or invalid.

Solution

Provide a valid Rit_ key in the Authorization header.

JSON Error Payload

{
  "error": {
    "code": 401,
    "message": "Unauthorized",
    "reason": "API key is missing or invalid.",
    "solution": "Provide a valid Rit_ key in the Authorization header."
  }
}

402

Payment Required

Reason

Token balance consumed.

Solution

Upgrade your plan or wait for the next cycle.

JSON Error Payload

{
  "error": {
    "code": 402,
    "message": "Payment Required",
    "reason": "Token balance consumed.",
    "solution": "Upgrade your plan or wait for the next cycle."
  }
}

403

Forbidden

Reason

Model not available on your plan.

Solution

Upgrade to access higher-tier models.

JSON Error Payload

{
  "error": {
    "code": 403,
    "message": "Forbidden",
    "reason": "Model not available on your plan.",
    "solution": "Upgrade to access higher-tier models."
  }
}

429

Too Many Requests

Reason

RPM or TPM limits reached.

Solution

Reduce frequency or upgrade for higher limits.

JSON Error Payload

{
  "error": {
    "code": 429,
    "message": "Too Many Requests",
    "reason": "RPM or TPM limits reached.",
    "solution": "Reduce frequency or upgrade for higher limits."
  }
}

500

Internal Server Error

Reason

Unexpected server issue.

Solution

Retry later or contact Ravonix support.

JSON Error Payload

{
  "error": {
    "code": 500,
    "message": "Internal Server Error",
    "reason": "Unexpected server issue.",
    "solution": "Retry later or contact Ravonix support."
  }
}