HAhappyscribe
Transcribe

Transcribe media

Creates a transcription order from a media URL. By default the order is submitted immediately (confirm: true) and processing starts as soon as the file is ingested. Pass confirm: false to preview pricing first, then submit with POST /orders/{id}/confirm.

The media url must be publicly accessible during ingestion. Once ingested, the file can safely be deleted from its source. Poll the order or use webhook_url to be notified of state changes.

post/transcribe

Request

  • Base URL
    https://www.happyscribe.com/api/v1
  • Auth
    API key in header Authorization

Request body

urlstring required

URL of the media file. Must be publicly accessible during ingestion.

languagestring required

BCP-47 language code of the media. See Languages.

workspace_idstring

ID of the workspace where the file is created. Required unless folder_id is given, in which case it is inferred from the folder. A wks_ id; integer workspace ids are still accepted.

service'auto' | 'pro'

auto for machine-made, pro for human-made.

confirmboolean

When false, the order stays incomplete until submitted via POST /orders/{id}/confirm.

folder_idinteger

ID of the folder to create the order in.

folderstring

Path of the folder to save the result in, e.g. path/to/my folder.

namestring

Name of the resulting file. Defaults to a name derived from the source file.

boostboolean

When true, pro orders are prioritized for faster turnaround. Has no effect on auto orders.

tagsstring[]

Tags to add to the resulting file.

webhook_urlstring

URL that receives a webhook every time the order changes state.

glossary_idsstring[]

Glossary IDs (gls_…) to apply. All IDs must belong to the specified workspace. Integer glossary ids are still accepted.

style_guide_idinteger

Style guide ID to apply. For pro orders, addons like verbatim and SDH are applied automatically from the style guide settings.

Example request

{
  "language": "en-GB",
  "workspace_id": "wks_01k6a2r9s8x7c2dvq3m5n6p4ab",
  "glossary_ids": [
    "gls_01k6b3m2n4p5q6r7s8t9v0w1xy"
  ]
}

Response

The created order.

idstring

Unique identifier for the order (UUID format).

folder_idinteger
state'incomplete' | 'waiting_for_payment' | 'submitted' | 'locked' | 'fulfilled' | 'failed' | 'canceled' | 'expired' | 'free_trial_submitted' | 'free_trial_fulfilled'

Current state of the order:

  • incomplete — created but not yet submitted
  • waiting_for_payment — waiting for payment to be processed
  • submitted — submitted, processing in progress
  • locked — insufficient credits or balance; unlock from the UI after topping up
  • fulfilled — completed successfully
  • failed — processing failed; see failure_reason
  • canceled — the order was canceled
  • expired — an old failed or incomplete order that has been cleaned up
  • free_trial_submitted / free_trial_fulfilled — legacy free-trial states
can_be_submittedboolean
outputs_idsstring[]

IDs (UUIDs) of the generated transcriptions or translations. Only present when the order is fulfilled.

failure_reason'ingestion_failed' | 'transcription_failed' | 'unknown'

Present when state is failed:

  • ingestion_failed — one or more files could not be imported; inspect ingestions[]
  • transcription_failed — the transcription/subtitling step failed; inspect transcriptions[]
  • unknown — no identifiable cause; contact support

Example response

{
  "id": "10b1edd9381d4a00a3d0db1ca1b3d0cf",
  "folder_id": 1,
  "state": "incomplete",
  "operations": [
    {
      "name": "transcription_translation",
      "type": "auto",
      "language": "en-US",
      "target_language": "es",
      "glossary_ids": []
    }
  ],
  "details": {
    "items": [
      {
        "input_id": 258,
        "filename": "TED+Talk",
        "pricing_unit_name": "minutes",
        "pricing_unit_count": 0.12,
        "turnaround_minutes": 1,
        "cents_per_unit": 20,
        "cents": 3,
        "credits": 0.12
      }
    ],
    "pricing_unit_name": "minutes",
    "pricing_unit_total_count": 0.12,
    "total_cents": 3,
    "total_credits": 0.12,
    "currency": "usd",
    "currency_symbol": "$",
    "minimum_charge": 50
  },
  "addons": [],
  "inputs": [
    {
      "transcription_id": "e5fb537cecc9436b93c04be2a9219001"
    }
  ],
  "can_be_submitted": true
}

Changes

No recorded changes to this operation across all 1 revision of this API.