Order Descriptions

Create Audio Description orders audio description on one media file in a single request. The media (an upload, a URL, or a file already in 3Play) and the order go in the same call.

How it works

1. Check the menu. List Products with type=descriptions lists what your project can order for the media's language.
2. Order. Create Audio Description with the media and orders[]. You get 202 Accepted and an id for the order.
3. Wait. Poll List Audio Descriptions with id, or wait for a callback if you passed a callback_url in your order.
4. Download. When status is complete, the order's downloads array holds a signed URL per file.

Every call authenticates with your API key. See Authentication.

Check the menu

List Products returns one row per variant, package and turnaround your project can order for the media's language. Pass type=descriptions and the media's source_language; package and turnaround narrow the list further. Availability depends on your project, so check before ordering.

GET /v3/products?type=descriptions&source_language=en-US

{
  "code": 200,
  "data": [
    { "type": "descriptions", "source_language": "en-US", "target_language": "en-US", "variant": "standard", "package": "launch", "turnaround": "standard" },
    { "type": "descriptions", "source_language": "en-US", "target_language": "en-US", "variant": "extended", "package": "launch", "turnaround": "standard" },
    { "type": "descriptions", "source_language": "en-US", "target_language": "en-US", "variant": "auto", "package": "accommodate", "turnaround": "standard" }
  ]
}

Order

{
  "media_file_id": 123456,
  "name": "Museum tour",
  "source_language": "en-US",
  "external_source_id": "museum-tour",
  "callback_url": "https://example.com/hooks/3play?token=abcd-1234",
  "orders": [ { "package": "accommodate", "turnaround": "standard", "variant": "auto" } ]
}

Send JSON, or multipart/form-data when uploading the file in source.

Media. Send exactly one of source (file upload), source_url (3Play downloads it; an authenticated URL must stay valid for at least 1 day), or media_file_id (a file already in 3Play).

Fields.

orders[] entry. One entry, with no target_language.

launch is the entry tier and studio the premium tier, with refine and accommodate between them.

The whole request is validated before anything is created. If any order asks for a package, turnaround, or language your project cannot order, the call returns 400 with the allowed values and nothing is ordered.

Response

202 Accepted, with the media and its orders in data:

{
  "code": 202,
  "data": {
    "media_file_id": 123456,
    "name": "Museum tour",
    "source_language": "en-US",
    "external_source_id": "museum-tour",
    "folder_name": null,
    "orders": [
      {
        "id": 987,
        "type": "descriptions",
        "media_file_id": 123456,
        "source_language": "en-US",
        "package": "accommodate",
        "turnaround": "standard",
        "status": "in_progress",
        "variant": "auto",
        "audio_description_id": 4567,
        "external_source_id": "museum-tour",
        "folder_name": null,
        "downloads": null
      }
    ]
  },
  "meta": {}
}

Each order's id is the ID of the service: pass it to List Audio Descriptions as the id filter, and the callback carries the same id. audio_description_id is a different ID and is not interchangeable with id. variant reads auto until 3Play chooses during processing, then standard or extended.

Track status

Poll List Audio Descriptions with the order's id, or set callback_url and skip polling. An unknown id returns an empty list. List Audio Descriptions also filters by media_file_id, external_source_id, status, and folder_name, with page and per_page (default 25, max 100).

A failed order carries failure, an object with type and message (the same shape as the v3 error object). It is omitted on every other status. The values below are illustrative.

"failure": { "type": "media_error", "message": "The media file could not be processed" }

Callbacks

When callback_url is set, 3Play sends one POST per order, when it reaches complete, failed, or cancelled. Nothing fires on intermediate status changes. The body is the same envelope a read of the order returns, downloads included:

{
  "code": 200,
  "data": {
    "id": 987,
    "media_file_id": 123456,
    "external_source_id": "museum-tour",
    "folder_name": null,
    "type": "descriptions",
    "source_language": "en-US",
    "package": "accommodate",
    "turnaround": "standard",
    "status": "complete",
    "downloads": [
      {
        "type": "vtt",
        "format_name": "WebVTT",
        "mime_type": "text/vtt",
        "url": "https://api.3playmedia.com/v3/downloads/abc123",
        "expires_at": "2026-11-01T12:00:00Z"
      }
    ]
  },
  "meta": {}
}

The download links expire; call List Audio Descriptions with id for fresh ones. Put an expiring token in the callback URL and check it on receipt; see Using Callback URLs. 3Play retries a callback that fails to deliver.

Download

Once status is complete, downloads holds one entry per file: type, format_name, mime_type, a signed url valid for 8 hours, and expires_at. Call List Audio Descriptions with id again for fresh links.

Which files are produced depends on the order.

Errors

Errors use the standard v3 error envelope.