REST API

API Reference

Complete REST API documentation for OrbitalsAI. Use these endpoints directly from any programming language or tool.

Base URL

https://api.orbitalsai.com/api/v1

Authentication

All API requests require authentication using your API key in the Authorization header:

headers

bash

Authorization: Bearer YOUR_API_KEY

Endpoints

POST

/audio/upload

Upload an audio file and get back the transcribed text.

Request Parameters

Parameter	Type	Required	Description
`file`	file	Yes	Audio file to transcribe. Max 200MB. Supported formats: WAV, MP3, OGG, FLAC, AAC, M4A, WMA, AMR, 3GP
`language`	string	No	Language code. Supported: english, french, hausa, igbo, kinyarwanda, swahili, twi, yoruba, zulu, arabic. Defaults to english if not specified.
`generate_srt`	boolean	No	Generate SRT subtitle file. Default: false

Example Request

bash

curl -X POST "https://api.orbitalsai.com/api/v1/audio/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@audio.mp3" \
  -F "language=hausa" \
  -F "generate_srt=true"

Response

response.json

javascript

{
  "task_id": 12345,
  "status": "pending",
  "original_filename": "audio.mp3",
  "srt_requested": false
}

Status Codes

201

Created - Transcription task created successfully

400

Bad Request - Invalid parameters or file format

401

Unauthorized - Invalid or missing API key

402

Payment Required - Insufficient balance

413

Payload Too Large - File size exceeds 200MB limit

429

Too Many Requests - Rate limit exceeded

GET

/audio/status/task_id

Get the status and result of an audio upload task.

Example Request

bash

curl -X GET "https://api.orbitalsai.com/api/v1/audio/status/12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (Completed)

response.json

javascript

{
  "status": "completed",
  "original_filename": "audio.mp3",
  "srt_requested": false,
  "result_text": "Hello, how are you?",
  "srt_content": null,
  "error": null,
  "timestamps": [
    { "start": 0.52, "end": 0.75, "text": "Hello," },
    { "start": 0.75, "end": 0.95, "text": "how" },
    { "start": 0.95, "end": 1.10, "text": "are" },
    { "start": 1.10, "end": 1.40, "text": "you?" }
  ]
}

timestamps is present for completed streaming sessions when word-level timestamps were enabled. It is null for regular pre-recorded transcription tasks.

Response (Processing)

response.json

javascript

{
  "task_id": 12345,
  "status": "processing",
  "original_filename": "audio.mp3",
  "srt_requested": false,
  "result_text": null,
  "srt_content": null
}

Status Codes

200

OK - Task retrieved successfully

401

Unauthorized - Invalid or missing API key

404

Not Found - Task ID not found

GET

/audio/tasks

Get all transcription tasks for the current user.

Example Request

bash

curl -X GET "https://api.orbitalsai.com/api/v1/audio/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

response.json

javascript

[
  {
    "task_id": 12345,
    "status": "completed",
    "original_filename": "audio.mp3",
    "srt_requested": false,
    "result_text": "Transcribed text...",
    "srt_content": null
  },
  {
    "task_id": 12344,
    "status": "processing",
    "original_filename": "audio2.mp3",
    "srt_requested": true,
    "result_text": null,
    "srt_content": null
  }
]

GET

/balance

Get your current account balance.

Example Request

bash

curl -X GET "https://api.orbitalsai.com/api/v1/billing/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

response.json

javascript

{
  "balance": 25.50,
  "last_updated": "2025-10-25T12:00:00Z"
}

GET

/usage

Get your usage history and statistics.

Example Request

bash

curl -X GET "https://api.orbitalsai.com/api/v1/billing/daily-usage" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

response.json

javascript

{
  "total_transcriptions": 145,
  "total_audio_minutes": 3240.5,
  "total_spent": 324.05,
  "current_month": {
    "transcriptions": 23,
    "audio_minutes": 512.3,
    "spent": 51.23
  }
}

Rate Limits

Standard Plan: 100 requests per minute

Pro Plan: 500 requests per minute

Enterprise: Custom limits

When you exceed the rate limit, you'll receive a 429 Too Many Requests response. The response includes a Retry-After header indicating when you can retry.

Error Responses

All error responses follow this format:

error.json

javascript

{
  "error": {
    "code": "insufficient_balance",
    "message": "Your account balance is too low. Please top up to continue.",
    "details": {
      "current_balance": 0.50,
      "required_balance": 2.00
    }
  }
}

Common Error Codes

`authentication_error`

The provided API key is invalid or has been revoked.

`insufficient_balance_error`

Your account balance is too low to complete this request.

`unsupported_file_error`

The uploaded file format is not supported or exceeds the 200MB size limit.

`unsupported_language_error`

The specified language is not currently supported.

`transcription_error`

The transcription failed to process. Please try again or contact support.

`timeout_error`

The transcription took too long to complete. Please try again with a smaller file.

Text Intelligence Services

LLM-powered text processing endpoints for multi-lingual translation, grounded summarization, and sensitive PII redaction.

OpenAPI Enums Reference

Languages (19)

Afrikaans, Amharic, Arabic, English, French, German, Hausa, Igbo, Isixhosa, Italian, Kinyarwanda, Sesotho, Setswana, Shona, Spanish, Swahili, Twi, Yoruba, Zulu

Summary Styles (3)

short (2-4 sentences executive summary), detailed (5-8 sentences), structured (6-key JSON output)

Domains (15 Verticals)

banking, customer support, ecommerce, education, fintech, general conversation, government services, healthcare, human resources, insurance, legal admin, logistics, telecom, travel hospitality, utilities

POST

/text/translate

Translates input text or transcript between any of the 19 supported languages.

curl

bash

curl -X POST https://api.orbitalsai.com/api/v1/text/translate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Sannu, yaya zan taimaka maka yau?",
    "source_language": "Hausa",
    "target_language": "English",
    "domain": "general conversation"
  }'

POST

/text/summarize

Summarizes text into concise, grounded English summaries. Supports short, detailed, or 6-key structured JSON output.

curl

bash

curl -X POST https://api.orbitalsai.com/api/v1/text/summarize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Customer called regarding delayed delivery of their debit card...",
    "language": "English",
    "style": "structured",
    "domain": "banking"
  }'

POST

/text/redact

Masks sensitive personal identifiable information (PII) with standardized placeholders (e.g. [PERSON_NAME], [BVN], [PHONE_NUMBER]).

curl

bash

curl -X POST https://api.orbitalsai.com/api/v1/text/redact \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "My name is John Doe and my BVN is 12345678901.",
    "language": "English",
    "domain": "fintech"
  }'

Webhooks

Coming Soon

Webhook support is coming soon. You'll be able to receive real-time notifications when transcription tasks are completed.

Official SDKs

We recommend using our official SDKs for a better development experience:

Python SDK

Automatic waiting, async support, and comprehensive error handling.

View Python Docs →

JavaScript SDK

Full TypeScript support for Node.js and browsers.

View JavaScript Docs →