Skip to content
Video Taxi Logo Video Taxi Logo Developer Docs

Summaries API Guide

This guide explains how to use the Video.Taxi Summarization GraphQL API to create a summary from an audio file via manual upload.

Introduction

The Video.Taxi Summarization API allows you to upload audio files, transcribe them, and generate structured summaries. This process involves generating a presigned URL for uploading the audio/video file to the storage, triggering transcription and speaker prediction, assigning speakers, and finally generating the summary.

Prerequisites

Before you begin, ensure you have:

  • A valid Video.Taxi Summaries API key (can be created via the Video.Taxi Summaries UI)
  • Access to the GraphQL API endpoint: https://summaries.video.taxi/api/v1/graphql
  • An audio file in a supported format (e.g., MP3, WAV, M4A)
  • A GraphQL client or cURL for making HTTP requests
  • Your user ID (retrievable via the getUserID query or from the Video.Taxi Summaries UI)
  • A valid summary type ID (retrievable via the getSummaryTypes query)

Making API Requests

The GraphQL endpoints can be used via any GraphQL client or simple HTTP requests. Here’s an example using cURL:

Terminal window
❯ curl -X POST https://summaries.video.taxi/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "query": "query GetSummary($summaryId: UUID!, $versionId: Int!) { summary(id: $summaryId, versionNumber: $versionId) { title, speaker { firstName, lastName }, summaryResult { data } } }",
    "variables": {
      "summaryId": "00000000-0000-0000-0000-000000000000",
      "versionId": 1
    }
  }'

API Operations

The following mutations and queries are used in the Video.Taxi Summarization API:

mutation createSummary($summary: CreateSummaryInput!) {
  createSummaryAsync(summary: $summary) {
    summaryId
    versionNumber
  }
}


mutation getUploadURL($uploadURLInput: GenerateUploadUrlInput!) {
  generateUploadUrl(input: $uploadURLInput) {
    uploadUrl
    id
    expiresInSeconds
    uploadId
  }
}


query getUserID {
  me {
    id
    username
    email
  }
}


query getSummaryTypes {
  summaryTypes {
    id
    label
    templateId
    description
    metadata
  }
}


mutation uploadFile($uploadInput: CompleteUploadInput!) {
  completeUpload(input: $uploadInput) {
    summaryId
    message
    success
  }
}


query GetSummary($id: UUID!, $version: Int!) {
  summary(id: $id, versionNumber: $version) {
    id
    organizationId
    status
  }
}

The full GraphQL schema can be found here.

Example Variables

Throughout this guide, the following variables structure is used. Replace the placeholder values with your actual data:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "version": 1,
  "summary": {
    "id": "00000000-0000-0000-0000-000000000000",
    "language": "en",
    "originalFilePath": "your-audio-file.mp3",
    "summaryTypeId": 1,
    "title": "Your Summary Title",
    "speakerList": [
      { "firstName": "Jane", "lastName": "Doe" },
      { "firstName": "John", "lastName": "Smith" }
    ]
  },
  "uploadURLInput": {
    "filename": "your-audio-file.mp3",
    "contentType": "audio/mpeg",
    "expiresInSeconds": 600
  },
  "uploadInput": {
    "id": "00000000-0000-0000-0000-000000000000",
    "uploadId": "draft/00000000-0000-0000-0000-000000000000/your-audio-file.mp3",
    "originalFilename": "your-audio-file.mp3",
    "language": "en"
  }
}

Note: The contentType in uploadURLInput must match the Content-Type header used when uploading the file.

Workflow

Step 1: Generate Upload URL

Call the generateUploadUrl mutation with uploadURLInput to obtain a pre-signed upload URL:

mutation getUploadURL($uploadURLInput: GenerateUploadUrlInput!) {
  generateUploadUrl(input: $uploadURLInput) {
    uploadUrl
    id
    expiresInSeconds
    uploadId
  }
}

The response will include a temporary URL where you can upload your file and an uploadId that you’ll need in subsequent steps.

Step 2: Upload the File

Upload the file to the returned uploadUrl using an HTTP PUT request. Include your user ID in the request headers:

Terminal window
export USER_ID="<USER_ID_FROM_getUserID_QUERY>"
export PRESIGNED_URL="<PRESIGNED_URL_FROM_STEP_1>"
export FILE_PATH="<PATH_TO_YOUR_AUDIO_FILE>"
curl -X PUT \
  -H "Content-Type: audio/mpeg" \
  -H "x-amz-meta-user-id: $USER_ID" \
  -T "$FILE_PATH" \
  "$PRESIGNED_URL"

Ensure the Content-Type header matches the contentType specified in step 1.

Step 3: Complete the Upload

Notify the backend that the upload is complete by calling the completeUpload mutation:

mutation uploadFile($uploadInput: CompleteUploadInput!) {
  completeUpload(input: $uploadInput) {
    summaryId
    message
    success
  }
}

Step 4: Create Summary Job

Call the createSummaryAsync mutation to initiate the summary creation process:

mutation createSummary($summary: CreateSummaryInput!) {
  createSummaryAsync(summary: $summary) {
    summaryId
    versionNumber
  }
}

This triggers the backend to transcribe the audio file and perform speaker prediction. You can monitor the progress by querying the summary status.

Step 4.1: Retrieve the Transcript

Once the status reaches SPEAKER_PREDICTED, you can retrieve the transcript to modify speaker assignments:

query GetSummary($id: UUID!, $version: Int!) {
  summary(id: $id, versionNumber: $version) {
    id
    organizationId
    status
    transcriptResult {
      sentences {
        text
        startMs
        endMs
        speakerId
      }
    }
  }
}

Variables:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "version": 1
}

This returns the transcript split into sentences with start/end times and automatically assigned speaker IDs (such as S1, S2, etc.).

Step 4.2: Update Speaker Assignments

You need to correct speaker assignments and can optionally assign agenda items by using the updateTranscript mutation. Note that you must include the complete sentences array from step 4.1, even if you’re only modifying a few entries:

mutation updateTranscript($transcriptInput: UpdateTranscriptionInput!) {
  updateTranscript(update: $transcriptInput)
}

Variables:

{
  "transcriptInput": {
    "summaryId": "00000000-0000-0000-0000-000000000000",
    "versionNumber": 1,
    "sentences": [
      {
        "text": "First sentence of the transcript",
        "startMs": 0,
        "endMs": 2760,
        "speakerId": "Jane Doe"
      },
      {
        "text": "Second sentence of the transcript",
        "startMs": 2760,
        "endMs": 5520,
        "speakerId": "John Smith"
      }
      // ... more sentences
    ],
    "agendaAssignment": []
  }
}

Important: The sentences array must contain all sentences from the original transcript. Omitting sentences will result in data loss as the transcript will be overwritten.

For complex speaker/agenda assignment workflows, it is recommended to use the frontend interface rather than the API.

Step 5: Start Summarization

Once speaker assignments are finalized (or if you’re skipping speaker assignment), call the startSummarizing mutation to generate the summary:

mutation startSummarizing($id: UUID!, $version: Int!) {
  startSummarizing(
    summaryId: $id
    versionNumber: $version
    overrideTemplate: false
    emptyTops: true
  )
}

Parameters:

  • overrideTemplate: Set to true only if agenda items were assigned in step 4.2
  • emptyTops: Set to true if no agenda items were assigned

Step 6: Retrieve the Final Summary

Query the completed summary using the summary query:

query GetSummary($id: UUID!, $version: Int!) {
  summary(id: $id, versionNumber: $version) {
    id
    summaryResult {
      data
    }
  }
}

The summaryResult.data field contains the final structured summary of your audio file.

Error Handling

If any step fails, check the response for error messages. Common issues include:

  • Expired upload URLs (regenerate with step 1)
  • Incorrect content type headers
  • Missing or invalid speaker assignments
  • Incomplete sentence arrays in transcript updates