API Documentation
Base URL: /apiWelcome to the official developer reference for the Nexakaunt Media Service. This REST microservice centralizes image optimization, asynchronous video transcoding via background workers, document storage, and dynamic on-the-fly image transformations.
Authentication & Gateway Headers
Microservice access control and identity injection
The Media Service uses a 3-tier multi-tenancy architecture. A single developer/master account can service hundreds of client companies with strict data isolation:
- Tier 1 (Master Account /
owner_id): Authenticated via your Master API Key or Bearer Token. Manages quotas and billing. - Tier 2 (Tenant Company /
company_id): Sent viaX-Company-Id. Media is strictly isolated per company so Company A never sees Company B's media. - Tier 3 (End User or Driver /
uploader_id): Sent viaX-User-Id. Tracks the specific driver or staff member who uploaded the file.
| Header | Description | Required |
|---|---|---|
| Authorization | Primary Master Developer authentication: Bearer mk_... (or Sanctum token for web console) |
Yes* |
| X-Api-Key / X-Media-Api-Key | Header aliases for the Media Service API Key (mk_...) |
Yes* |
| X-Company-Code / X-Company-Id | Tenant / Company Code (e.g. XR11proMAX). Strictly scopes uploads and queries to that company. |
Recommended |
| X-User-Id | Identifier of the driver, staff member, or customer (persisted strictly as uploader_id) |
Optional |
X-User-Id DOES NOT authenticate requests. Any upload from mobile apps (Flutter / React Native) directly to Media Service must supply the organization's Media API key in the X-Api-Key or Authorization header. Sending only an application auth token will result in 401 Unauthorized.
Direct Connection Guide (Without SDK)
Zero DependenciesConnect directly using standard HTTP, cURL, or S3 protocol
You do not need to install an SDK to communicate with the Media Service. The entire service runs on standard REST endpoints and MinIO/S3 compatible storage. Any framework, language, or frontend can connect directly.
Upload directly from Auth, Finance, or Fleet services using standard Laravel HTTP client:
use Illuminate\Support\Facades\Http; $response = Http::withHeaders([ 'Authorization' => 'Bearer ' . env('MEDIA_SERVICE_API_KEY'), 'X-User-Id' => (string) auth()->id(), 'X-Company-Id' => (string) auth()->user()->company_id, ])->attach( 'images', file_get_contents($request->file('avatar')->getRealPath()), $request->file('avatar')->getClientOriginalName() )->post('https://media-api.atithisewa.com/api/media/upload', [ 'access_type' => 'public', // or 'private' ]); $fileId = $response->json('data.0.id');
Display responsive images or stream video directly via URL parameters without any API call:
<!-- Responsive Image with Dynamic Resize and Quality --> <img src="https://media-api.atithisewa.com/api/images/{FILE_ID}/serve?w=400&h=300&q=80" alt="Avatar" /> <!-- Direct File Download --> <a href="https://media-api.atithisewa.com/api/media/{FILE_ID}/download">Download File</a> <!-- Smooth Video Streaming with HTTP 206 Partial Range seeking --> <video controls src="https://media-api.atithisewa.com/api/videos/{FILE_ID}/serve"></video>
curl -X POST https://media-api.atithisewa.com/api/media/upload \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "X-User-Id: user_123" \ -F "images=@/path/to/invoice.pdf" \ -F "access_type=private"
Connect directly using the MinIO Access Key & Secret Key minted in your Media Console:
// In config/filesystems.php of any service 'nexakaunt_s3' => [ 'driver' => 's3', 'key' => env('AWS_ACCESS_KEY_ID'), 'secret' => env('AWS_SECRET_ACCESS_KEY'), 'region' => 'us-east-1', 'bucket' => env('AWS_BUCKET', 'nexakaunt-media'), 'endpoint' => env('AWS_ENDPOINT', 'https://media-api.atithisewa.com:9000'), 'use_path_style_endpoint' => true, ],
Official SDKs Integration Guide
3-Tier OperationsStrongly typed SDKs for PHP/Laravel and JavaScript/TypeScript
Auto-discovering Laravel package with NexakauntMedia Facade and typed MediaAsset DTO.
use Nexakaunt\Media\Facades\NexakauntMedia; // Tier 2: Upload with user/tenant isolation $asset = NexakauntMedia::upload( $request->file('avatar'), folder: 'avatars', isPrivate: false, ownerId: (string) auth()->id() ); // Tier 1: 0ms Instant URL generation $thumbUrl = NexakauntMedia::thumbnailUrl($asset->id, 200); // Private short-lived signed view URL $signedUrl = NexakauntMedia::getPrivateViewUrl($asset->id, expiryMinutes: 15);
Zero-dependency TypeScript client for React, Vue, Next.js, and Node.js with client-side security safeguards.
import { NexakauntMedia } from '@nexakaunt/media-sdk';
// Client-safe init (No secrets in frontend bundle)
const media = new NexakauntMedia({
baseUrl: process.env.NEXT_PUBLIC_MEDIA_URL,
});
// Tier 1: 0ms instant thumbnail (zero network trip)
export function Avatar({ fileId }) {
const url = media.thumbnailUrl(fileId, 120);
return <img src={url} className="rounded-full w-10 h-10" />;
}
/api/media/upload
Upload images, videos, or document files. Images are synchronously optimized and converted to WebP. Videos are stored raw and an asynchronous transcoding job is queued.
| Field | Type | Required | Description |
|---|---|---|---|
| images[] | File Array | Yes | Array of media files (Max 50MB per file) |
| access_type | String | No | public or private (default: public) |
| disk | String | No | public, local, s3, or minio |
curl -X POST https://media.nsantosh.com/api/media/upload \
-H "X-User-Id: 9d5e8a7b-1234-5678-90ab-cdef12345678" \
-H "X-Company-Id: 442e8a7b-1234-5678-90ab-cdef12345678" \
-F "images[]=@/path/to/photo.jpg" \
-F "access_type=private"
const formData = new FormData();
formData.append('images[]', fileInput.files[0]);
formData.append('access_type', 'private');
const response = await fetch('/api/media/upload', {
method: 'POST',
headers: {
'X-User-Id': '9d5e8a7b-1234-5678-90ab-cdef12345678',
'X-Company-Id': '442e8a7b-1234-5678-90ab-cdef12345678'
},
body: formData
});
const data = await response.json();
use Illuminate\Support\Facades\Http;
$response = Http::withHeaders([
'X-User-Id' => '9d5e8a7b-1234-5678-90ab-cdef12345678',
'X-Company-Id' => '442e8a7b-1234-5678-90ab-cdef12345678',
])->attach(
'images[]', file_get_contents($filePath), 'photo.jpg'
)->post('https://media.nsantosh.com/api/media/upload', [
'access_type' => 'private'
]);
{
"message": "1 file(s) uploaded successfully",
"data": [
{
"id": "9d5e8a7b-1234-5678-90ab-cdef12345678",
"url": "https://media.nsantosh.com/api/media/9d5e8a7b-1234-5678-90ab-cdef12345678/serve",
"filename": "photo.webp",
"mime_type": "image/webp",
"size": 245678,
"processing_status": "completed",
"thumbnail_url": null,
"created_at": "2026-07-30T15:45:00.000000Z"
}
]
}
/api/media/{id}
Retrieve complete metadata for a specific media record by UUID. Private files require X-User-Id matching the owner or company.
/api/media/{id}/serve
Streams the raw file with HTTP caching headers (ETag, Cache-Control). Supports range requests for video seeking and instant image resize parameters.
| Parameter | Type | Description | Example |
|---|---|---|---|
| w | Integer | Target width in pixels | ?w=400 |
| h | Integer | Target height in pixels | ?h=300 |
| q | Integer | WebP quality level (1-100) | ?q=80 |
| thumbnail | Boolean | Set to 1 to retrieve video thumbnail poster |
?thumbnail=1 |
| token | String | Signed 1-hour HMAC view token for private browser images | ?token=hmac... |
/api/media/{id}/view-token
When media is uploaded with access_type: private, direct unauthenticated access to /serve is rejected with 403 Forbidden.
Standard browser <img> tags and mobile widgets (Image.network) cannot send custom HTTP headers.
Calling this endpoint generates a short-lived (1-hour) signed HMAC view token and returns a pre-signed URL with ?token=... ready for direct display.
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Master API Key formatted as Bearer <API_KEY> |
| X-Company-Id | Conditional | Tenant company identifier matching the media item's company |
| X-User-Id | Conditional | User UUID matching the media item's owner |
// 1. Fetch pre-signed temporary URL:
final res = await dio.get(
'https://media-api.atithisewa.com/api/images/$mediaId/view-token',
options: Options(headers: {
'Authorization': 'Bearer $apiKey',
'X-Company-Id': companyCode,
}),
);
final String signedUrl = res.data['data']['url'];
// 2. Render directly in Flutter widget:
Image.network(
signedUrl,
fit: BoxFit.cover,
errorBuilder: (context, error, stack) => Icon(Icons.broken_image),
);
curl -X GET "https://media-api.atithisewa.com/api/media/019482fa-bc44-7128-98e1-d2e46b9a1012/view-token" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-Company-Id: comp_fleet_101"
const res = await fetch(`https://media-api.atithisewa.com/api/media/${mediaId}/view-token`, {
headers: {
'Authorization': `Bearer ${apiKey}`,
'X-Company-Id': companyId
}
});
const { data } = await res.json();
// Directly assign to HTML Image element:
document.getElementById('docPreview').src = data.url;
use Illuminate\Support\Facades\Http;
// Backend signs URL and passes it to the mobile client
$response = Http::withHeaders([
'Authorization' => 'Bearer ' . $apiKey,
'X-Company-Id' => $companyCode,
])->get("https://media-api.atithisewa.com/api/media/{$mediaId}/view-token");
$signedUrl = $response->json('data.url');
{
"data": {
"url": "https://media-api.atithisewa.com/api/media/019482fa-bc44-7128-98e1-d2e46b9a1012/serve?token=eyJtZWRpYUl...",
"serve_url": "/api/media/019482fa-bc44-7128-98e1-d2e46b9a1012/serve?token=eyJtZWRpYUl...",
"filename": "citizenship_card.webp",
"mime_type": "image/webp",
"expires_in": 3600
}
}
/api/media/{id}/status
Poll asynchronous video processing status. Status values:
/api/media/stats/usage
Get real-time storage quota usage for the company passed in X-Company-Id. Returns total bytes used, company quota cap, and total media counts.