Quickstart
Before jumping into the below example, make sure you have your API key (see the Authentication guide).
Otherwise, you're all set!
Preparing a Transcript
Wordcab accepts various inputs, but we'll start with a sample transcript in .txt format to keep things simple. The structure is as follows:
# Timestamps are optional, and can be included anywhere on the line.
# Transcripts must have a speaker label, followed by a colon, and then the text that was spoken.
[00:00:08 --> 00:00:11] Lauren: Thank you for calling Nissan. My name is Lauren. Can I have your name?
[00:00:11 --> 00:00:13] Sam: Yeah, my name is John Smith.
# Every new speaker turn (or utterance) must be on a newline, and cannot be on the same line.
Below is a sample sales call transcript correctly formatted for Wordcab use. Let's save this text to a .txt file and use it as a source for Wordcab's /summarize endpoint.
Choosing Your Summary Type
A summary type is a particular way to convey condensed information. Wordcab allows you to generate several useful summary types. These vary in size and format and accommodate many use cases.
Wordcab has several summary types to choose from (see the Summary Types guide), but for the Quickstart guide, we'll start with the narrative summary type.
Generating a "Narrative" Summary
We'll start with the narrative summary type: a detailed, chronological account of what happened in the transcript that reduces transcript or audio read-time by 10x. Here's an example of a narrative summary type:
Lauren and Sam discuss how much it would cost to update the map in their car. Lauren says the newest version of the map is version 7.7, which is $99 plus shipping and tax. Lauren says they would recommend taking advantage of the extra $50 off before it expires.
The summary length is proportional to the size of the text transcript, and you can expect around 90% less text in summary than in the transcript on average.
Choosing Your Summary's Source
We'll be using a .txt transcript as the source, so you'll need to set source to generic. See the Accepted Sources guide to learn more about the summary sources Wordcab accepts.
You will also need a human-readable title for your summary job for the display_name query parameter.
Choosing Your Summary's Level of Detail
To start a narrative summary job, you'll be using the /summarize endpoint and need to include a few required parameters.
One of these required parameters is summary_lens, a comma-separated string that includes one or more numbers, from 1 to 5. Every number represents a narrative summary with a different level of detail.
1: The transcript is shortened by 13x-15x.3: The transcript is reduced by 9x-11x.5: The transcript has been shortened by 5x-8x.
If you include more than one level of detail (ex. summary_lens=1,3,5) you will get back that many summaries: for example, a narrative summary of length 1, a narrative summary of length 3, and a narrative summary of length 5.
Initiating Your Summary Job
Finally, include the .txt in your request. Each programming language accepts requests with attached files differently - below, you'll find examples for cURL, Python, and Node.
curl --request POST \
--url 'https://wordcab.com/api/v1/summarize?source=generic&summary_type=narrative&summary_lens=1,3,5' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--form transcript=@"/path/to/sales_call.txt"
import requests
url = "https://wordcab.com/api/v1/summarize"
headers = {
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_KEY"
}
params = {
"display_name": "Sales Call Summary",
"source": "generic",
"summary_type": "narrative",
"summary_lens": "1,5"
}
file_path = "/path/to/sales_call.txt"
files = {
"transcript": open(file_path, "rb")
}
response = requests.post(url, headers=headers, params=params, files=files)
print(response.text)
const sdk = require('api')('@wordcab/v1.0#1md5cejl3domqcf');
sdk.auth('YOUR_API_KEY');
sdk.post('/summarize', {}, {
display_name: 'Sales Call Summary',
source: 'generic',
summary_type: 'narrative',
summary_lens: '1,5',
Accept: 'application/json',
form: 'transcript=@"/path/to/sales_call.txt"'
})
.then(res => console.log(res))
.catch(err => console.error(err));
If the request were successful, you would get back a job_name in your response. We can use this to poll the API for job status.
Polling the API
To check the status of your summary job, you'll need to use the /jobs endpoint. You'll need to include the job_name you received in the response from the /summarize endpoint.
curl --request GET \
--url 'https://wordcab.com/api/v1/jobs/YOUR_JOB_NAME' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY'
import requests
url = "https://wordcab.com/api/v1/jobs/YOUR_JOB_NAME"
headers = {
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
print(response.text)
const sdk = require('api')('@wordcab/v1.0#1md5cejl3domqcf');
sdk.auth('YOUR_API_KEY');
sdk.get('/jobs/YOUR_JOB_NAME', {}, {
Accept: 'application/json'
})
.then(res => console.log(res))
.catch(err => console.error(err));
The response will include a status field. If the status is complete, you can move on to the next step. If the status is pending, you'll need to wait a few seconds and try again. Learn more about the Job Statuses in our documentation.
Here's an example of a successful response:
{
"job_name": "job_UiqoBWqnd5ag7eDz7YTpn8n9pHWVUR4c",
"job_status": "SummaryComplete",
"time_started": "2022-10-22T09:45:11.989010Z",
"transcript_id": "generic_transcript_PoJ5TKxGFDyk7UebAHnQ6CPbiR66BrXG",
"display_name": "Sales Call",
"settings": {
"pipeline": "transcribe,summarize",
"split_long_utterances": false,
"ephemeral_data": false,
"only_api": true
},
"source": "generic",
"summary_details": {
"summary_id": "narrative_summary_JgSQdCUuDcAxJkwzXnPKHkmuDfDT3SKH",
"summary_type": "narrative",
"summary_lens": [
1,
3,
5
]
},
"metadata": {},
"tags": [],
"time_completed": "2022-10-22T09:45:15.665778+00:00"
}
Retrieving Your Summary
Once your summary job is complete, you can retrieve the summary by using the /summaries endpoint. You'll need to include the summary_id you received in the response from the /jobs endpoint.
curl --request GET \
--url 'https://wordcab.com/api/v1/summaries/YOUR_SUMMARY_ID' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY'
import requests
url = "https://wordcab.com/api/v1/summaries/YOUR_SUMMARY_ID"
headers = {
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
print(response.text)
const sdk = require('api')('@wordcab/v1.0#1md5cejl3domqcf');
sdk.auth('YOUR_API_KEY');
sdk.get('/summaries/YOUR_SUMMARY_ID', {}, {
Accept: 'application/json'
})
.then(res => console.log(res))
.catch(err => console.error(err));
The response will include a summary field, which is the summary of the transcript you requested. You can use this summary in your application or save it to a file.
The summary field is divided into multiple lengths. For example, if you requested a narrative summary of length 1,3,5, you will get back a summary field with three keys: 1, 3, and 5. Each key will contain a summary of that length.
Here's an example of a summary response to the sales_call.txt with a length of 3:
"3": {
"structured_summary": [
{
"end": "00:01:58",
"start": "00:00:08",
"summary": "Sam notes that they were calling to see how much it would cost to update the map in their car. Lauren talks about how the newest version of the map is version 7.7, which is $99 plus shipping and tax. Lauren says they would recommend taking advantage of the extra $50 off before it expires.",
"summary_html": "<span class=\"speaker_b\">SPEAKER B</span> notes that they were calling to see how much it would cost to update the map in their car. <span class=\"speaker_a\">SPEAKER A</span> talks about how the newest version of the map is version 7.7, which is $99 plus shipping and tax. <span class=\"speaker_a\">SPEAKER A</span> says they would recommend taking advantage of the extra $50 off before it expires.",
"timestamp_end": 118000,
"timestamp_start": 8000,
"transcript_segment": [...]
}
]
},
Congratulations! You've successfully created a summary of a transcript using the Wordcab API. 🎉
Next Steps
There are many configuration options you can use to create perfect summaries. If you'd like to learn more about the Wordcab API, you can start by reading our API Concepts documentation.
For more configuration options, you should read our Guides documentation, which will describe the different types of summaries, the accepted sources, job statuses, and so much more.
Updated over 1 year ago