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, hausa, igbo, yoruba, swahili, pidgin, kinyarwanda. 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

{
  "task_id": 12345,
  "status": "completed",
  "original_filename": "audio.mp3",
  "srt_requested": true,
  "result_text": "Welcome to OrbitalsAI. This is a test transcription in Hausa language.",
  "srt_content": "1\n00:00:00,000 --> 00:00:03,500\nWelcome to OrbitalsAI...\n\n"
}

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

/tasks

Get all transcription tasks for the current user.

Example Request

bash

curl -X GET "https://api.orbitalsai.com/api/v1/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.

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 →