API Reference

Base URL:

https://api.videototext.dev

Response envelope

Successful responses use:

{
  "data": {},
  "meta": {}
}

Errors use Problem Details:

{
  "type": "VALIDATION_ERROR",
  "title": "Validation failed",
  "status": 400,
  "detail": "Invalid request",
  "errorCode": "VALIDATION_ERROR"
}

Transcription modes

Mode	Credits	Notes
balanced	1 credit per minute	Default mode
precision	2 credits per minute	Higher-accuracy option

Task statuses

Status	Meaning
QUEUED	The task is waiting for processing capacity.
PROCESSING	The task is currently being transcribed.
SUCCEEDED	The transcript is ready.
FAILED	The task failed and may include showError.
CANCELED	The task was canceled.

POST /v1/uploads

Create a signed upload URL.

Request:

{
  "filename": "meeting.mp4",
  "mimetype": "video/mp4"
}

Response:

{
  "data": {
    "uploadUrl": "https://storage.example.com/signed-upload-url",
    "fileKey": "uploads/example.mp4",
    "fileUrl": "https://static.example.com/uploads/example.mp4",
    "uploadId": "00000000-0000-0000-0000-000000000000",
    "expiresAt": "2026-06-06T10:00:00.000Z"
  },
  "meta": {}
}

POST /v1/uploads/{uploadId}/operations/complete

Validate the uploaded object, read media duration, and create an asset.

Path parameters:

Name	Type	Description
uploadId	UUID	Upload session ID returned by POST /v1/uploads.

Request:

{
  "fileKey": "uploads/example.mp4",
  "fileUrl": "https://static.example.com/uploads/example.mp4",
  "filename": "meeting.mp4",
  "mimetype": "video/mp4",
  "fileSize": 10485760
}

Response:

{
  "data": {
    "assetId": "00000000-0000-0000-0000-000000000000"
  },
  "meta": {}
}

Common errors include UPLOAD_SESSION_NOT_FOUND, UPLOAD_SESSION_EXPIRED, UPLOAD_SIZE_MISMATCH, UPLOAD_MIMETYPE_MISMATCH, and UPLOAD_DURATION_UNREADABLE.

POST /v1/tasks

Create a transcription task from an uploaded asset.

For retry-safe task creation, see Idempotency.

Request:

{
  "assetId": "00000000-0000-0000-0000-000000000000",
  "language": "Auto",
  "timestampMode": "CHUNK",
  "transcriptionMode": "balanced"
}

Fields:

Field	Type	Required	Notes
assetId	UUID	Yes	Asset returned by upload completion.
language	string	No	Defaults to Auto. Supported languages use lowercase names such as english, spanish, or chinese.
timestampMode	string	No	CHUNK or WORD. Defaults to CHUNK.
transcriptionMode	string	No	Public mode key: balanced or precision. Defaults to balanced.

Response:

{
  "data": {
    "task": {
      "transcriptId": "00000000-0000-0000-0000-000000000000",
      "status": "QUEUED",
      "language": "Auto",
      "timestampMode": "CHUNK",
      "transcriptionMode": "balanced",
      "billedCredits": "1.500000000000"
    }
  },
  "meta": {
    "pollAfterMs": 1500
  }
}

Task create and task detail responses always include transcriptionMode with the public mode key used for billing and result processing.

GET /v1/tasks/{taskId}

Return the current task status and transcript result fields needed by clients.

Path parameters:

Name	Type	Description
taskId	UUID	data.task.transcriptId returned by POST /v1/tasks.

Response:

{
  "data": {
    "task": {
      "transcriptId": "00000000-0000-0000-0000-000000000000",
      "status": "SUCCEEDED",
      "showError": null,
      "fullText": "Welcome to the meeting.",
      "chunks": [
        {
          "seq": 0,
          "startMs": 0,
          "endMs": 2200,
          "text": "Welcome to the meeting.",
          "speakerKey": null,
          "speakerName": null,
          "wordStartIndex": 0,
          "wordEndIndex": 1
        }
      ],
      "words": [
        {
          "text": "Welcome",
          "startMs": 0,
          "endMs": 600
        }
      ],
      "sourceDurationMs": 90400,
      "language": "Auto",
      "resultLanguage": "english",
      "timestampMode": "CHUNK",
      "transcriptionMode": "balanced",
      "billedCredits": "1.500000000000",
      "createdAt": "2026-06-06T09:00:00.000Z"
    }
  },
  "meta": {}
}