AI API

This API provides an advanced conversational AI optimized for natural, witty, and context-aware interactions. Suitable for ChatBots, Coding, AI Agents, Short replies, writing memos, etc.

Endpoint

POST /api/v1/ai

Request Parameters

The following parameters are accepted in the request body:

Field	Type	Required	Description
prompt	string	Yes	The user’s input message.
persona	string	Optional	Defines the AI’s character (e.g., “Sarcastic Bot”, “Helpful Doctor”).

Request Examples

Choose your preferred method to interact with the Heavstal AI API:

cURL

curl -X POST https://heavstal.com.ng/api/v1/ai \
-H "Content-Type: application/json" \
-H "x-api-key: <YOUR_API_KEY>" \
-d '{"prompt": "Explain quantum physics like I am 5", "persona": "A 21th century Physicists with 5 PhDs"}'

JavaScript (Fetch)

const response = await fetch('https://heavstal.com.ng/api/v1/ai', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '<YOUR_API_KEY>'
  },
  body: JSON.stringify({
    prompt: "Explain quantum physics like I'm 5",
    persona: "A 21th century Physicists with 5 PhDs"
  })
});

const res = await response.json();
console.log(res.data);

Heavstal SDK

import { ai } from '@heavstal/api';

const chat = await ai.chat(
  "Explain quantum physics like I'm 5",
  "A 21th century Physicists with 5 PhDs"
);

console.log(chat.response);

Python

import requests

url = "https://heavstal.com.ng/api/v1/ai"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "<YOUR_API_KEY>"
}
payload = {
    "prompt": "Explain quantum physics like I'm 5",
    "persona": "A 21th century Physicists with 5 PhDs"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json()["data"])

Response Examples

Success Response

{
  "status": "success",
  "creator": "HEAVSTAL TECH",
  "data": {
    "model": "gemini-3.1-pro",
    "response": "..."
  }
}

Error Response

{
  "status": "error",
  "error": "Missing required parameter: prompt"
}