REST API

Imports

Endpoint Overview

Method	Endpoint	Description
POST	`/api/v1/imports/check-quota`	Check budget
POST	`/api/v1/imports`	Upload audio file
GET	`/api/v1/imports/{importId}`	Query import status
GET	`/api/v1/imports`	Get import list

POST /api/v1/imports/check-quota

Check whether the user's monthly budget is sufficient to upload an audio file of a given duration. We recommend calling this API for a pre-check before uploading, so you avoid discovering that the budget is insufficient only after uploading a large file.

Authentication

Header: X-API-Key (see Authentication)

Request Parameters

Parameter	Location	Type	Required	Description
`duration_ms`	body	integer	Yes	Audio duration (milliseconds, 1 second to 10 hours)

Request Example

curl -X POST "https://vas-poc.vurbo.ai/api/v1/imports/check-quota" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -H "Content-Type: application/json" \
  -d '{"duration_ms": 3600000}'

Success Response

HTTP 200

{
  "data": {
    "allowed": true,
    "remaining_budget": 48.48,
    "is_unlimited": false,
    "duration_minutes": 25,
    "estimated_cost": 0.4236,
    "remaining_minutes": 2864
  }
}

Response Field Description

Field	Type	Description
`data.allowed`	boolean	Whether the upload is allowed (`true` when the budget is not exceeded)
`data.remaining_budget`	float \| null	Remaining monthly budget (USD); `null` when there is no budget limit
`data.is_unlimited`	boolean	Whether there is no budget limit
`data.duration_minutes`	integer	Estimated audio duration (minutes, rounded up)
`data.estimated_cost`	float	Estimated STT processing cost (USD)
`data.remaining_minutes`	integer \| null	Equivalent STT minutes available within the remaining budget; `null` when there is no budget limit

Specific Error Codes

This endpoint has no specific error codes; it may only return common authentication errors.

POST /api/v1/imports

Description

Upload an audio file for speech recognition and translation. After a successful upload, processing runs in the background, and you can track progress through the Query import status API.

Authentication

Header: X-API-Key (see Authentication)

Request Parameters (multipart/form-data)

Parameter	Type	Required	Description
`file`	file	Yes	Audio file (mp3/wav/m4a, max 500MB)
`transcription_languages`	string	Yes	Transcription languages (JSON array string, e.g. `'["zh-TW"]'`)
`translation_languages`	string	No	Translation languages (JSON array string, e.g. `'["en-US"]'`)
`recognition_mode`	string	Yes	Recognition mode: `single` (single speaker) / `multi_speaker` (multiple speakers)
`summary_template`	string	No	Summary template identifier (max 50 characters; must be an enabled `summary` category slug)
`terminology`	string	No	Terminology list (JSON object string; see format below)
`fuzzy_correction`	string	No	Fuzzy correction rules (JSON object string; see format below)
`translation_dict`	string	No	Translation dictionary (JSON array string; see format below)
`callback_url`	string	No	Webhook callback URL (notifies on completion/failure, max 2048 characters)

Webhook Notification: Once callback_url is set, you receive an import.completed event when the import finishes and an import.failed event when it fails. See the Webhook Guide.

Text Processing Parameter Formats

Terminology (terminology): Improves recognition accuracy for specific terms

{
  "zh-TW": [
    { "term": "Speaker Diarization", "boost": 1.5 },
    { "term": "Real-time Transcription", "boost": 1.5 }
  ]
}

Use the language code as the key and the term array as the value
term: Term text (required, max 100 characters)
boost: Weight (optional, default 1.0)
Up to 500 terms per language

Fuzzy Correction (fuzzy_correction): Automatically corrects common recognition errors

{
  "zh-TW": [
    { "correct": "Speaker Diarization", "incorrect": ["Speaker Diorization", "Speaker Diarizaion"] }
  ]
}

Use the language code as the key and the correction rule array as the value
correct: Correct term (required, max 200 characters)
incorrect: List of incorrect variants (required, each item max 200 characters)

Translation Dictionary (translation_dict): Specifies how proper nouns are translated

[
  { "source": "Speaker Diarization", "translations": { "en-US": "Speaker Diarization" } }
]

source: Source term (required, max 200 characters)
translations: Translation for each language (use the language code as the key; each translation text max 200 characters)
Up to 50 entries

Request Example

Basic Request

curl -X POST "https://vas-poc.vurbo.ai/api/v1/imports" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -F "file=@meeting.mp3" \
  -F 'transcription_languages=["zh-TW"]' \
  -F 'translation_languages=["en-US"]' \
  -F "recognition_mode=multi_speaker"

Request with Text Processing Settings

curl -X POST "https://vas-poc.vurbo.ai/api/v1/imports" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -F "file=@meeting.mp3" \
  -F 'transcription_languages=["zh-TW"]' \
  -F 'translation_languages=["en-US"]' \
  -F "recognition_mode=multi_speaker" \
  -F 'terminology={"zh-TW": [{"term": "Speaker Diarization", "boost": 1.5}]}' \
  -F 'fuzzy_correction={"zh-TW": [{"correct": "Speaker Diarization", "incorrect": ["Speaker Diorization"]}]}' \
  -F 'translation_dict=[{"source": "Speaker Diarization", "translations": {"en-US": "Speaker Diarization"}}]'

Request with Webhook Callback

curl -X POST "https://vas-poc.vurbo.ai/api/v1/imports" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -F "file=@meeting.mp3" \
  -F 'transcription_languages=["zh-TW"]' \
  -F 'translation_languages=["en-US"]' \
  -F "recognition_mode=multi_speaker" \
  -F "callback_url=https://your-server.com/webhooks/vas"

Success Response

HTTP 202

{
  "data": {
    "import_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending",
    "stage": null,
    "progress": 0,
    "message": null,
    "original_filename": "meeting.mp3",
    "file_size": "15.2 MB",
    "task_id": null,
    "error_code": null,
    "error_message": null,
    "created_at": "2026-02-23T10:00:00.000Z",
    "updated_at": "2026-02-23T10:00:00.000Z"
  }
}

Response Field Description

Field	Type	Description
`data.import_id`	string	Import ID (UUID)
`data.status`	string	Status: `pending`
`data.stage`	string \| null	Processing stage (initially `null`)
`data.progress`	integer	Progress percentage (initially `0`)
`data.message`	string \| null	Processing message
`data.original_filename`	string	Original file name
`data.file_size`	string	File size (formatted)
`data.task_id`	string \| null	Task ID (populated only after processing completes)
`data.error_code`	string \| null	Error code (populated only on failure)
`data.error_message`	string \| null	Error message (populated only on failure)
`data.created_at`	string	Creation time (ISO 8601)
`data.updated_at`	string	Last update time (ISO 8601)

Specific Error Codes

Error Code	HTTP Status	Description	Recommended Action
`import_file_too_large`	413	File size exceeds the 500MB limit	Compress or split the file
`import_invalid_format`	415	Unsupported audio format	Use mp3/wav/m4a format
`stt_quota_exceeded`	402	STT quota exceeded	Wait for the next month's quota reset or adjust your plan

GET /api/v1/imports/{importId}

Description

Query the processing status and progress of a specific import task.

Authentication

Header: X-API-Key (see Authentication)

Request Parameters

Parameter	Location	Type	Required	Description
`importId`	path	string	Yes	Import ID (UUID)

Request Example

curl -X GET "https://vas-poc.vurbo.ai/api/v1/imports/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

Success Response

HTTP 200

{
  "data": {
    "import_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "stage": "transcribing",
    "progress": 45,
    "message": "Recognizing speech...",
    "original_filename": "meeting.mp3",
    "file_size": "15.2 MB",
    "task_id": null,
    "error_code": null,
    "error_message": null,
    "created_at": "2026-02-23T10:00:00.000Z",
    "updated_at": "2026-02-23T10:05:00.000Z"
  }
}

Response Field Description

Field	Type	Description
`data.status`	string	Status: `pending` / `processing` / `completed` / `failed`
`data.stage`	string \| null	Processing stage: `converting` / `transcribing` / `translating` / `summarizing`
`data.progress`	integer	Progress percentage (0-100)
`data.task_id`	string \| null	Task ID after processing completes (can be used with the Tasks API)
`data.error_code`	string \| null	Error code on failure
`data.error_message`	string \| null	Error message on failure

The remaining fields are the same as the POST /api/v1/imports response.

status Transitions

pending → processing → completed
                    → failed

stage Processing Stages

Stage	Description
`converting`	Converting audio format
`transcribing`	Recognizing speech
`translating`	Translating
`summarizing`	Generating summary

Edge Case for the `completed` Status (v1.3.5)

When an audio file produces no recognizable speech content—due to silence, low volume, noise, or a recognition language that does not match the audio—the system still finishes with completed (not failed), and task_id is generated normally, but the transcript entries for the corresponding task are an empty array. The client should load the data via GET /api/v1/sse/history/transcribe/{taskId} and then decide whether to show an empty state based on the sentence count. See File Import Guide – Behavior When Audio Cannot Be Recognized.

Specific Error Codes

Error Code	HTTP Status	Description	Recommended Action
`import_not_found`	404	Import task not found	Verify that importId is correct

Parameter	Location	Type	Required	Description
`per_page`	query	integer	No	Items per page (default 20)

Request Example

curl -X GET "https://vas-poc.vurbo.ai/api/v1/imports?per_page=20" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

Success Response

HTTP 200

{
  "data": [
    {
      "import_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "stage": null,
      "progress": 100,
      "message": null,
      "original_filename": "meeting.mp3",
      "file_size": "15.2 MB",
      "task_id": "660f9500-f30c-52e5-b827-557766550000",
      "error_code": null,
      "error_message": null,
      "created_at": "2026-02-23T10:00:00.000Z",
      "updated_at": "2026-02-23T10:15:00.000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 20,
    "total": 55
  }
}

Response Field Description

Field	Type	Description
`data`	array	List of import tasks (each field is the same as the Query import status response)
`meta.current_page`	integer	Current page number
`meta.last_page`	integer	Last page number
`meta.per_page`	integer	Items per page
`meta.total`	integer	Total number of items

Specific Error Codes

This endpoint has no specific error codes; it may only return common authentication errors.

Version: V1.5.7 Last Updated: 2026-05-20

Entries

Speakers