VerbalizeIt Developer API


Overview

The VerbalizeIt API allows developers to submit files for translation or transcription directly, without using the Customer Dashboard. The Developer API supports all of the same options and features provided in the Customer Dashboard, allowing you to customize your tasks as needed.

This documentation covers Version 2.0 of the API. All API methods urls are prefixed with /v2.


Ruby Gem

VerbalizeIt has a Ruby gem that wraps Version 2.0 of the API. You can view the gem on GitHub or download it from RubyGems.


Hosts and Environments

VerbalizeIt supports two environments for developers: Production and Staging. VerbalizeIt does not support requests via HTTP, all requests must use HTTPS.

Staging

https://stagingapi.verbalizeit.com/v2/

Tasks submitted to Staging are translated automatically with dummy content and returned within 6 minutes. This is a free service for developers to use to integrate with VerbalizeIt.

Production

https://api.verbalizeit.com/v2/

Tasks submitted to Production are translated by the VerbalizeIt community of translators. This is pay-per-use services, and developers are charged for translation performed in this environment.


Authentication

The API requires you to authenticate with your API key to perform any requests. Your API key is found in the Customer Dashboard, in the API section. A key is provided for both Production and Staging environments. This key must be set as the X-API-KEY header.

Be sure to set theX-API-KEY header as the key with each request.


Tasks

Tasks are the primary unit work on the VerbalizeIt system. A task usually represents one file- a Word Document, an MP3, a Vimeo video, etc.

Each task consists of, at minimum:

  • A unique identifier
  • An operation
  • An input file to translate or transcribe
  • A source language of the original file
  • A target language to translate

Price Quote and Starting Tasks

By default, a task is not started immediately after it is posted. After creating a task, the task returns a price quote. This gives you (or your users) the opportunity to evaluate if this translation is within your budget.

After creating a task, call the start method to begin translation. Alternately, you can pass the start parameter when creating the task to start immediately.

Operations

Each task specifies an operation, which lets VerbalizeIt know exactly what do to with the files you provide. This can be translation or transcription. You must provide an operation when creating a task.

Operation Code Description Final File
Text Translation text_translation Translate a document from one language to another. A file matching your original document as closely as possible, with translated text
Audio Transcription audio_transcription Transcribe an audio file into timestamped text, in the same language or between languages. A SubRip (.srt) subtitle file. If an .srt file is provided when creating the task, the same timestamps will be used in the translated file. If not provided, timestamps will be added every 7 seconds
Video Transcription video_transcription Transcribe a video file into timestamped text, in the same language or between languages. A SubRip (.srt) subtitle file. If an .srt file is provided when creating the task, the same timestamps will be used in the translated file. If not provided, timestamps will be added every 7 seconds

Languages

Tasks must be submitted using an appropriate language pair.

Operation Supported Language Pairs
Text Translation English (U.S.) -> Non-English
Non-English -> English (U.S.)
Audio Transcription English (U.S.) -> English (U.S.)
Non-English -> Non-English (same language)
English (U.S.) -> Non-English
Non-English -> English (U.S.)
Video Transcription English (U.S.) -> English (U.S.)
Non-English -> Non-English (same language)
English (U.S.) -> Non-English
Non-English -> English (U.S.)

Files and Media Resource URLs

Input media files to VerbalizeIt can be provided in a variety of methods and formats, depending on the file type and operation. In the case of text files, which are often smaller, it is appropriate to post the file directly to the API. For video files, which can be many GB in size, it is more appropriate to submit a URL to the file.

All filenames must include a valid and supported extension.

Operation Submitting File Supported Filetypes
Text Translation File post .docx, .po, .pptx, .resx, .ts, .txt, .xlf, .xliff, .xlsx, .yml, Android (.xml), iOS (.strings)
Audio Transcription File post .mp3, .wav
  Media Resource URL .mp3, .wav
Video Transcription Media Resource URL .mp4, Vimeo URL
  Media Resource URL + File post (original captions) URL: .mp4, Vimeo URL, File: .srt

Postback and Status URLs

The VerbalizeIt API can post to a user-designated endpoint when a task is complete or changes state. This is configured by the postback_url and status_url parameters while submitting a task.

Both urls are optional. You can provide either, both, or none.

If the postback_url parameter is set, a finished, translated file will be posted to the designated URL as an HTTP multipart post as soon as the file has completed.

POST to postback URL
{
  "task_id": "T24609A",
  "file": {file}
}

If the status_url parameter is set, VerbalizeIt will post to the designated URL whenever the task changes states through the system.

It will also post with status deleted if a task is deleted.

POST to status URL
{
  "task_id": "T24609A",
  "status": "in_review"
}

Errors

The HTTP response status code corresponds to the error received.

Code Definition Example
400 Bad Request e.g. Invalid or missing parameters, or unreadable file.
401 Unauthorized e.g. Request may not have included an API Key
403 Forbidden e.g. Accessing a task that does not belong to your account.
500 Internal Server Error e.g. Something broke on our side. We will be notified and look into the issue immediately.

4xx errors may provide additional details in their responds, if available.

{
  "errors":{
    "source_language":[
      "Not a valid language code"
    ],
    "target_language":[
      "Not a valid language code"
    ]
  }
}

Languages

List Languages

List available languages for translation. Each language consists of a name, a language/region code, and a language direction.

The language/region code is used to set the source and target language when posting a new task.

GET /v2/languages

Parameters

None

Response

Status: 200 OK
[
  {
    "name":"English (U.S.)",
    "language_region_code":"eng-US",
    "language_direction":"left to right"
  },
  {
    "name":"Arabic",
    "language_region_code":"ara-AE",
    "language_direction":"right to left"
  },
  {
    "name":"Bosnian",
    "language_region_code":"tur-TR",
    "language_direction":"left to right"
  },
  {
    "name":"French",
    "language_region_code":"fra-Fr",
    "language_direction":"left to right"
  }
]

Tasks

List Tasks

Lists all submitted tasks, sorted by creation date.

GET /v2/tasks

Parameters

Name Type Description
start integer (optional) Index of starting task
limit integer (optional) Maximum number of tasks to return
status string (optional) Find tasks matching status
  • "preview" - not yet started, awaiting confirmation
  • "processing" - preparing file for translation
  • "translating" - a translator is working
  • "expert_review" - proofreading and review by an expert translator
  • "final_qa" - quality assurance check and file processing
  • "complete" - finished and ready to download

Response

Status: 200 OK
{
  "total" : 100,
  "start" : 0,
  "limit" : 10,
  "tasks" : [
    {
      id: "TX1234",
      status: "complete",
      created_at: "2014-10-09T11:56:02-04:00",
      operation: "text_translation",
      source_language: "eng-US",
      target_language: "spa-ES",
      price_currency: "usd",
      price_amount: 11.22,
      download_url: "https://api.verbalizeit.com/v2/tasks/TX1234/completed_file",
      source_download_url: "https://api.verbalizeit.com/v2/tasks/TX1234/source_file",
      source_filename: "marketing_materials.docx",
      unit_count: 66,
      unit_type: "word",
      translation_units: 16,
      translation_units_complete: 16,
      special_instructions: 'Use a formal tone',
      project_name: "Marketing Materials",
      url: "http://www.verbalizeit.com/v2/tasks/TCAAA"
      due_at: "2014-10-13T11:56:02-04:00",
      completed_at: "2014-10-09T12:11:06-04:00"
      postback_url: "https://api.mycompany.com/finished_task",
      status_url: "https://api.mycompany.com/task_changed_status",
      rush_order: false,
      priority: false,
      translator:{
        name: "Jenny S.",
        avatar: "http://assets.verbalizeit.com/..../translator.jpg"
      },
      reviewer:{
        name: "Stephen D.",
        avatar: "http://assets.verbalizeit.com/..../revewier.jpg"
      },
      quality_score: 95.69
    }
  ]
}

Show

Show task status

GET /v2/tasks/:task_id

Parameters

None

Response

Status: 200 OK
{
  id: "TX1234",
  status: "complete",
  created_at: "2014-10-09T11:56:02-04:00",
  operation: "text_translation",
  source_language: "eng-US",
  target_language: "spa-ES",
  price_currency: "usd",
  price_amount: 11.22,
  download_url: "https://api.verbalizeit.com/v2/tasks/TX1234/completed_file",
  source_download_url: "https://api.verbalizeit.com/v2/tasks/TX1234/source_file",
  source_filename: "marketing_materials.docx",
  unit_count: 66,
  unit_type: "word",
  translation_units: 16,
  translation_units_complete: 16,
  special_instructions: 'Use a formal tone',
  project_name: "Marketing Materials",
  url: "http://www.verbalizeit.com/v2/tasks/TCAAA"
  due_at: "2014-10-13T11:56:02-04:00",
  completed_at: "2014-10-09T12:11:06-04:00"
  postback_url: "https://api.mycompany.com/finished_task",
  status_url: "https://api.mycompany.com/task_changed_status",
  rush_order: false,
  priority: false,
  translator:{
    name: "Jenny S.",
    avatar: "http://assets.verbalizeit.com/..../translator.jpg"
  },
  reviewer:{
    name: "Stephen D.",
    avatar: "http://assets.verbalizeit.com/..../revewier.jpg"
  },
  quality_score: 95.69
}

Create

Create a new task

Note: A due_at is returned when creating a task. This is the estimated time and date of completion if the task were started immediately. This date may be used internally or communicated to third parties, recognizing that the date is subject to change if there is significant delay between creating a starting a task.

POST /v2/tasks

Parameters

Name Type Description
operation string Operation to perform (text_translation, audio_transcription, video_transcription)
source_language string Language/Region code of original input media
target_language string Language/Region code for final output media
file file (optional - if media_resource_url provided) Input media file to translate/transcribe.
This may be a text document or audio file.
Files must be named to include a valid, supported extension.
media_resource_url string (optional - if file provided) URL of input media file to translate/transcribe.
This may be an audio file, video file, or Vimeo url.
postback_url string (optional) URL to post the translated file when task is completed.
status_url string (optional) URL to post status updates as the task moves through the VerbalizeIt system.
start boolean (optional) Elect to start translating the task immediately. Default FALSE
rush_order boolean (optional) Rush orders are completed in half the time of standard orders, if base turnaround time is 48 hours or more. Cost is 40% more than a standard order. Default FALSE
priority boolean (optional) Similar to rush order but no timeline guarantees or cost implications. It is useful when submitting a large batch of tasks to indicate which task you want to prioritize first. Default FALSE
special_instructions string (optional) Any extra information, context, or requirements to assist the translator.
{
  "operation": "text_translation",
  "source_language": "eng-US",
  "target_language": "fra-FR",
  "file": {file post, "sample.docx"},
  "postback_url": "https://api.mycompany.com/finished_task",
  "status_url": "https://api.mycompany.com/task_changed_status"
}
{
  "operation": "audio_transcription",
  "source_language": "eng-US",
  "target_language": "eng-US",
  "file": {file post, "sample.mp3"},
  "postback_url": "https://api.mycompany.com/finished_task",
  "status_url": "https://api.mycompany.com/task_changed_status"
}
{
  "operation": "audio_transcription",
  "source_language": "eng-US",
  "target_language": "eng-US",
  "media_resource_url": "https://resources.mycompany.com/my_file.mp3",
  "postback_url": "https://api.mycompany.com/finished_task",
  "status_url": "https://api.mycompany.com/task_changed_status"
}
{
  "operation": "video_transcription",
  "source_language": "eng-US",
  "target_language": "eng-US",
  "media_resource_url": "https://resources.mycompany.com/my_file.mp4",
  "postback_url": "https://api.mycompany.com/finished_task",
  "status_url": "https://api.mycompany.com/task_changed_status"
}
{
  "operation": "video_transcription",
  "source_language": "eng-US",
  "target_language": "eng-US",
  "media_resource_url": "https://resources.mycompany.com/my_file.mp4",
  "file": {file post, "my_subtitles.srt"},
  "postback_url": "https://api.mycompany.com/finished_task",
  "status_url": "https://api.mycompany.com/task_changed_status"
}

Response

Status: 201 OK
  {
    id: "TX1234",
    status: "processing",
    created_at: "2014-10-09T11:56:02-04:00",
    operation: "text_translation",
    source_language: "eng-US",
    target_language: "spa-ES",
    price_currency: "usd",
    price_amount: 11.22,
    download_url: "https://api.verbalizeit.com/v2/tasks/TX1234/completed_file",
    source_download_url: "https://api.verbalizeit.com/v2/tasks/TX1234/source_file",
    source_filename: "marketing_materials.docx",
    unit_count: 66,
    unit_type: "word",
    translation_units: 16,
    translation_units_complete: 16,
    special_instructions: 'Use a formal tone',
    project_name: "Marketing Materials",
    url: "http://www.verbalizeit.com/v2/tasks/TCAAA"
    due_at: "2014-10-13T11:56:02-04:00",
    completed_at: "2014-10-09T12:11:06-04:00"
    postback_url: "https://api.mycompany.com/finished_task",
    status_url: "https://api.mycompany.com/task_changed_status",
    rush_order: false,
    priority: false,
    translator:{},
    reviewer:{},
    quality_score: null
  }

Start

Start a task in preview state. This kicks off work by VerbalizeIt and the translator community.

POST /v2/tasks/:task_id/start

Parameters

None

Response

Status: 200 OK
{}

Update

Update the priority for a task. Priority is the only parameter that is currently accepted for update.

PUT /v2/tasks/:task_id

Parameters

Name Type Description
priority boolean Similar to rush order but no timeline guarantees or cost implications. Set the priority to TRUE to move this task ahead of other tasks submitted in a batch. Set the priority to FALSE to deprioritize the task.

Response

Status: 200 OK
{
  id: "TX1234",
  status: "translating",
  created_at: "2014-10-09T11:56:02-04:00",
  operation: "text_translation",
  source_language: "eng-US",
  target_language: "spa-ES",
  price_currency: "usd",
  price_amount: 11.22,
  download_url: "https://api.verbalizeit.com/v2/tasks/TX1234/completed_file",
  source_download_url: "https://api.verbalizeit.com/v2/tasks/TX1234/source_file",
  source_filename: "marketing_materials.docx",
  unit_count: 66,
  unit_type: "word",
  translation_units: 16,
  translation_units_complete: 16,
  special_instructions: 'Use a formal tone',
  project_name: "Marketing Materials",
  url: "http://www.verbalizeit.com/v2/tasks/TCAAA"
  due_at: "2014-10-13T11:56:02-04:00",
  completed_at: null
  postback_url: "https://api.mycompany.com/finished_task",
  status_url: "https://api.mycompany.com/task_changed_status",
  rush_order: false,
  priority: true,
  translator:{
    name: "Jenny S.",
    avatar: "http://assets.verbalizeit.com/..../translator.jpg"
  },
  reviewer:{
    name: "Stephen D.",
    avatar: "http://assets.verbalizeit.com/..../revewier.jpg"
  },
  quality_score: null
}
  

Delete

Delete a task. The delete endpoint will return a 403 along with an error message if the task cannot be deleted because work has already been started. If a task has a status of "preview" or "processing" it can be deleted, all other statuses will return a 403. The status can be retrieved with a request to the Show endpoint. Customers will not be billed for successfully deleted tasks however they will be billed in full for tasks where work has already been started.

DELETE /v2/tasks/:task_id

Parameters

None

Response

Status: 200 OK
{}

Download Completed File

Download a completed file. Task must be in the complete state.

Note: You must provide the API Key header when downloading a file. This prevents unauthorized users from downloading a file if they have your Task ID. Files can also be downloaded by logging into the customer dashboard.
GET /v2/tasks/:task_id/completed_file

Parameters

None

Response

Status: 200 OK

File download

Interpretations

Create

Schedule a call with an interpreter. This provides a price quote. The interpretation will need to be 'confirmed' to schedule.

POST /v2/scheduled_interpretations

Input

Name Type Description
start_time date/time string "2015-02-18 18:15:40 -0500", at least 1 day in the future
duration integer Length of the call in minutes
source_language string Language/Region code of original input media
target_language string Language/Region code for final output media
customer_conference_code string (optional) Customer dial-in conference code, consisting of 5 numbers (e.g. "12345"). Assigned automatically if not provided.
special_instructions string (optional) Any additional instructions or context for the translator. This field is optional for the API create, but is highly recommended.

Response

Status: 200 OK
  {
  "id":"I1153B",
  "customer_conference_code":"17763",
  "start_time":"2015-02-18T18:31:19-05:00",
  "duration":12,
  "source_language":"eng-US",
  "target_language":"spa-ES",
  "complete":"false",
  "estimate":
    {
    "price_per_minute":1.75,
    "total":21.0
    },
  "phone_number":"18001234567"
}

Confirm

Confirm an interpretation

POST /v2/scheduled_interpretations/:interpretation_id/confirm

Input

None

Response

Status: 200 OK
{}

Show

Show an interpretation

GET /v2/scheduled_interpretations/:interpretation_id

Parameters

None

Response

Status: 201 OK
  {
  "id":"I1153B",
  "customer_conference_code":"17763",
  "start_time":"2015-02-18T18:31:19-05:00",
  "duration":12,
  "source_language":"eng-US",
  "target_language":"spa-ES",
  "complete":"false",
  "estimate":
    {
    "price_per_minute":1.75,
    "total":21.0
    },
  "phone_number":"18001234567"
}