Getting Started
BelakStudio is the official creator and operator of Arat Kilo Movies (aratkilomovies.com.et and aratkilomovies.pro.et). We provide programmatic access to movie & TV series metadata, instant catalog search, and responsive high-speed video player embedding for third-party websites and applications.
Authentication & API Keys
Authenticate requests by including your secret API key in the standard HTTP Authorization header:
Authorization: Bearer bks_live_YOUR_API_KEY
Alternatively, you can provide your key via the X-API-Key request header. Never expose your secret API keys in client-side code, GitHub commits, or public URLs.
Base URLs
All v1 API requests must target the production gateway:
Supported Endpoints
/movies
Returns a paginated list of movies. Supports filtering by genre, release year, search query, and sorting.
GET /api/v1/movies?search=Addis&page=1&limit=10\nAuthorization: Bearer bks_live_SAMPLE_KEY
{
"success": true,
"count": 1,
"pagination": {
"page": 1,
"limit": 10,
"total": 1,
"total_pages": 1
},
"data": [
{
"id": "bks_mov_001",
"title": "Echoes of Entoto",
"slug": "echoes-of-entoto",
"release_year": 2025,
"genre": "Drama, Mystery",
"rating": 8.4,
"duration_minutes": 118,
"poster_url": "https://belakstudio.pro.et/assets/images/addis-ababa.jpg"
}
]
}
/movies/{id}
Retrieves deep metadata for a specific movie including synopsis, genres, cast, and playback stream links when authorized.
GET /api/v1/movies/bks_mov_001\nAuthorization: Bearer bks_live_SAMPLE_KEY
{
"success": true,
"data": {
"id": "bks_mov_001",
"title": "Echoes of Entoto",
"overview": "A detective uncovers secrets hidden in the misty highlands of Addis Ababa.",
"release_year": 2025,
"genre": "Drama, Mystery",
"rating": 8.4,
"streaming_available": true,
"playback": {
"format": "hls",
"stream_url": "https://stream.aratkilomovies.com.et/sample/master.m3u8",
"expires_in": 3600
}
}
}
/series
Returns television series catalogs with season counts and episode summaries.
GET /api/v1/series?genre=Drama\nAuthorization: Bearer bks_live_SAMPLE_KEY
{
"success": true,
"count": 1,
"data": [
{
"id": "bks_ser_001",
"title": "Bole Nights",
"seasons_count": 2,
"release_year": 2024,
"genre": "Drama, Tech"
}
]
}
/health
Public ping endpoint to verify gateway availability without deducting quota.
GET /api/v1/health
{
"status": "healthy",
"service": "BelakStudio Gateway",
"timestamp": "2026-10-19T14:00:00Z"
}
Code Examples (Node.js & Python)
JavaScript (Fetch / Node.js 18+)
const API_KEY = process.env.BELAK_API_KEY || 'bks_live_YOUR_KEY_HERE';
async function fetchMovies(query = '') {
const url = `https://belakstudio.pro.et/api/v1/movies?search=${encodeURIComponent(query)}`;
const response = await fetch(url, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
});
if (!response.ok) {
const error = await response.json();
throw new Error(`API Error [${error.code}]: ${error.error}`);
}
const { data, pagination, plan_info } = await response.json();
console.log(`Fetched ${data.length} movies. Quota remaining: ${plan_info.quota_remaining}`);
return data;
}
fetchMovies('Addis').catch(console.error);
Python (Requests 2.30+)
import os
import requests
API_KEY = os.getenv("BELAK_API_KEY", "bks_live_YOUR_KEY_HERE")
BASE_URL = "https://belakstudio.pro.et/api/v1"
def get_movie_details(movie_id: str):
headers = {
"Authorization": f"Bearer {API_KEY}",
"Accept": "application/json"
}
resp = requests.get(f"{BASE_URL}/movies/{movie_id}", headers=headers, timeout=10)
if resp.status_code == 200:
return resp.json()["data"]
elif resp.status_code == 429:
raise Exception("Quota or Rate limit exceeded. Check Retry-After header.")
else:
raise Exception(f"Request failed [{resp.status_code}]: {resp.text}")
if __name__ == "__main__":
movie = get_movie_details("bks_mov_001")
print(f"Title: {movie['title']} ({movie['release_year']})")
Responsive HTML5 Video Embed Integration
BelakStudio provides high-performance responsive streaming iframe embeds for both movies and TV/anime episodes with 12 automatic server fallbacks. Embed into your CMS, blog, or custom web platform with a single snippet.
| Type | URL Format | Required Parameters |
|---|---|---|
| Movie Embed | https://aratkilomovies.com/api/embed/movie.php?id={TMDB_ID}&key={API_KEY} | id, key |
| TV / Series Embed | https://aratkilomovies.com/api/embed/tv.php?id={TMDB_ID}&s={SEASON}&e={EPISODE}&key={API_KEY} | id, s, e, key |
<!-- BelakStudio & AratKiloMovies Responsive 16:9 Video Container -->
<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%; border-radius: 12px; background: #000;">
<iframe
src="https://aratkilomovies.com/api/embed/movie.php?id=550&key=YOUR_API_KEY"
style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: 0;"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen>
</iframe>
</div>
Rate Limits & Plans (In ETB)
Requests are monitored in real time. Rate limits prevent automated denial-of-service, and monthly quotas ensure fair use. When a limit is breached, the gateway returns HTTP 429 Too Many Requests with a Retry-After: 60 header.
Error Codes
| HTTP | Error Code | Meaning / Resolution |
|---|---|---|
| 401 | AUTH_KEY_MISSING | Missing Authorization header in request. |
| 401 | AUTH_KEY_INVALID | Provided API key does not exist or has invalid signature. |
| 403 | AUTH_KEY_REVOKED | Key was revoked in the developer dashboard. |
| 429 | QUOTA_EXCEEDED | Monthly quota exhausted. Upgrade your subscription tier. |
| 429 | RATE_LIMIT_EXCEEDED | Exceeded requests per minute threshold. Delay before retry. |
| 404 | ENDPOINT_NOT_FOUND | Requested path or HTTP method is not supported. |