DEV3 Echolace
Sign inGet started

DEV3 Echolace REST API

Base URL /api/v1 · Authenticate with Authorization: Bearer n3k_… · OpenAPI 3.1 JSON

get/api/v1/mescope: read

The workspace this key belongs to

get/api/v1/membersscope: read

List members

Parameters: role (query)

get/api/v1/usagescope: read

Usage for the current billing period and the minute balance

get/api/v1/mediascope: read

List recordings

Parameters: q (query), folderId (query), limit (query)

post/api/v1/mediascope: write

Upload a recording (multipart field "file") or import by URL (JSON {"url"})

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "format": "uri"
    },
    "name": {
      "type": "string",
      "maxLength": 160
    },
    "folderId": {
      "type": "string",
      "pattern": "^[0-9a-f]{24}$"
    }
  },
  "additionalProperties": false
}
get/api/v1/media/{id}scope: read

Get a recording

Parameters: id (path)

delete/api/v1/media/{id}scope: write

Delete a recording

Parameters: id (path)

get/api/v1/transcriptsscope: read

List transcripts

Parameters: status (query), q (query), limit (query)

post/api/v1/transcriptsscope: write

Start a transcription for a recording (reserves minutes)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "mediaId": {
      "type": "string",
      "pattern": "^[0-9a-f]{24}$"
    },
    "language": {
      "type": "string",
      "minLength": 2,
      "maxLength": 8
    },
    "vocabularyId": {
      "type": "string",
      "pattern": "^[0-9a-f]{24}$"
    },
    "idempotencyKey": {
      "type": "string",
      "maxLength": 80
    }
  },
  "required": [
    "mediaId"
  ],
  "additionalProperties": false
}
get/api/v1/transcripts/{id}scope: read

Get a transcript with speakers and word timestamps

Parameters: id (path)

delete/api/v1/transcripts/{id}scope: write

Delete a transcript

Parameters: id (path)

get/api/v1/transcripts/{id}/exportscope: read

Export as txt, docx, pdf, srt, vtt or json

Parameters: id (path), format (query)

get/api/v1/transcripts/{id}/revisionsscope: read

List revisions

Parameters: id (path)

post/api/v1/transcripts/{id}/revisionsscope: write

Save an edited transcript as the next revision (409 version_conflict with a merge proposal when behind)

Parameters: id (path)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "baseVersion": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "doc": {
      "type": "object",
      "properties": {
        "speakers": {
          "minItems": 1,
          "maxItems": 20,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 20
              },
              "label": {
                "type": "string",
                "minLength": 1,
                "maxLength": 60
              },
              "colour": {
                "type": "string",
                "maxLength": 20
              }
            },
            "required": [
              "id",
              "label",
              "colour"
            ],
            "additionalProperties": false
          }
        },
        "segments": {
          "maxItems": 20000,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 20
              },
              "speaker": {
                "type": "string",
                "minLength": 1,
                "maxLength": 20
              },
              "start": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "end": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "words": {
                "minItems": 1,
                "maxItems": 20000,
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 20
                    },
                    "t0": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9007199254740991
                    },
                    "t1": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9007199254740991
                    },
                    "text": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 200
                    },
                    "conf": {
                      "type": "number",
                      "minimum": 0,
                      "maximum": 1
                    }
                  },
                  "required": [
                    "id",
                    "t0",
                    "t1",
                    "text",
                    "conf"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "required": [
              "id",
              "speaker",
              "start",
              "end",
              "words"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "speakers",
        "segments"
      ],
      "additionalProperties": false
    },
    "note": {
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "baseVersion",
    "doc"
  ],
  "additionalProperties": false
}
get/api/v1/transcripts/{id}/aiscope: read

AI outputs (summary, chapters, key points, action items, quotes, translations)

Parameters: id (path)

post/api/v1/transcripts/{id}/aiscope: write

Run an AI task (simulated engine by default)

Parameters: id (path)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "task": {
      "type": "string",
      "enum": [
        "summary",
        "chapters",
        "key_points",
        "action_items",
        "quotes",
        "translate"
      ]
    },
    "language": {
      "type": "string"
    },
    "targetLanguage": {
      "type": "string"
    },
    "maxItems": {
      "type": "integer",
      "minimum": 1,
      "maximum": 12
    },
    "idempotencyKey": {
      "type": "string",
      "maxLength": 80
    }
  },
  "required": [
    "task"
  ],
  "additionalProperties": false
}
get/api/v1/subtitlesscope: read

Subtitle sets of a transcript

Parameters: transcriptId (query)

post/api/v1/subtitlesscope: write

Generate subtitles (42 characters x 2 lines, 1-7 s cues by default)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "transcriptId": {
      "type": "string",
      "pattern": "^[0-9a-f]{24}$"
    },
    "language": {
      "type": "string"
    },
    "settings": {
      "type": "object",
      "properties": {
        "maxChars": {
          "type": "integer",
          "minimum": 20,
          "maximum": 80
        },
        "maxLines": {
          "type": "integer",
          "minimum": 1,
          "maximum": 3
        },
        "minDurMs": {
          "type": "integer",
          "minimum": 300,
          "maximum": 5000
        },
        "maxDurMs": {
          "type": "integer",
          "minimum": 1000,
          "maximum": 15000
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "transcriptId"
  ],
  "additionalProperties": false
}
post/api/v1/translatescope: write

Translate a transcript (and build its subtitles)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "transcriptId": {
      "type": "string",
      "pattern": "^[0-9a-f]{24}$"
    },
    "targetLanguage": {
      "type": "string",
      "minLength": 2,
      "maxLength": 8
    },
    "idempotencyKey": {
      "type": "string",
      "maxLength": 80
    }
  },
  "required": [
    "transcriptId",
    "targetLanguage"
  ],
  "additionalProperties": false
}
get/api/v1/voicesscope: read

Voice catalogue

get/api/v1/voiceoversscope: read

List voiceovers

post/api/v1/voiceoversscope: write

Render a voiceover from script blocks (billed per 1,000 characters)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 160
    },
    "blocks": {
      "minItems": 1,
      "maxItems": 200,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 5000
          },
          "voice": {
            "type": "string",
            "maxLength": 60
          },
          "pauseAfterMs": {
            "type": "integer",
            "minimum": 0,
            "maximum": 5000
          }
        },
        "required": [
          "text"
        ],
        "additionalProperties": false
      }
    },
    "settings": {
      "default": {},
      "type": "object",
      "properties": {
        "speed": {
          "type": "number",
          "minimum": 0.5,
          "maximum": 2
        },
        "pitchShift": {
          "type": "number",
          "minimum": -12,
          "maximum": 12
        },
        "gapMs": {
          "type": "integer",
          "minimum": 0,
          "maximum": 500
        }
      },
      "additionalProperties": false
    },
    "idempotencyKey": {
      "type": "string",
      "maxLength": 80
    }
  },
  "required": [
    "title",
    "blocks",
    "settings"
  ],
  "additionalProperties": false
}
get/api/v1/voiceovers/{id}scope: read

Get a voiceover (download with ?download=wav|mp3)

Parameters: id (path)

get/api/v1/jobs/{id}scope: read

Job status and progress

Parameters: id (path)

post/api/v1/jobs/{id}/cancelscope: write

Cancel a queued or running job (reserved minutes are refunded)

Parameters: id (path)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {},
  "additionalProperties": {}
}
get/api/v1/vocabulariesscope: read

Custom vocabularies

post/api/v1/vocabulariesscope: write

Create a vocabulary

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "terms": {
      "minItems": 1,
      "maxItems": 500,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "term": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "soundsLike": {
            "maxItems": 10,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 80
            }
          },
          "boost": {
            "type": "number",
            "minimum": 0,
            "maximum": 10
          }
        },
        "required": [
          "term"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "name",
    "terms"
  ],
  "additionalProperties": false
}
get/api/v1/searchscope: read

Search across transcripts; hits carry timestamps

Parameters: q (query), limit (query)