Transform articles into audio assets (API) ᴮᴱᵀᴬ

👍

This is a beta offering. You can request access to this beta feature through your JWX representative.

By using this documentation, you are agreeing to abide by the terms of the JWP Beta Program Agreement.

An article-to-audio workflow uses the JWX Management API to transform article content into audio assets. It defines how content is submitted, processed, and delivered as audio.

The workflow includes submitting content for transformation, monitoring processing, previewing the generated audio, and publishing the asset.

Prerequisites

Generate and publish an asset

Follow these steps:

1. Submit the article text to generate audio (for example, verbatim or prompt). The API creates a new project, returns a transformation run ID, and indicates that processing has started (queued).

   cURL

   curl --request PUT \
        --url https://api.jwplayer.com/v2/sites/{SITE_ID}/transformation_transform \
        --header 'Authorization: <SECRET>' \
        --header 'accept: application/json' \
        --header 'content-type: application/json' \
        --data '{
          "external_id": "ARTICLE_ID",
          "transformation_agent_id": "TRANSFORMATION_AGENT_ID",
          "input": {
            "asset_type": "article",
            "title": "ARTICLE_TITLE",
            "content": "ARTICLE_TEXT",
            "source_url": "ARTICLE_URL",
            "author": "AUTHOR",
            "thumbnail_url": "ARTICLE_THUMBNAIL_URL"
          }
        }'
   
   

   
   

2. Copy the id from the API response.

   📘

   This is also the transformation_run_id returned as part of the webhook notification in step 4.

   
   
   JSON

   {
     "created": "2026-01-23T17:02:33+00:00",
     "id": "TRANSFORMATION_RUN_ID",
     ...
     "state": "queued",
     ...
     "type": "transformation_run"
   }
   
   

3. Register a webhook to receive status updates for the transformation run.

   cURL

   curl --request POST \
        --url https://api.jwplayer.com/v2/webhooks/ \
        --header 'Authorization: <SECRET>' \
        --header 'accept: application/json' \
        --header 'content-type: application/json' \
        --data '
   {
     "metadata": {
       "name": "Transformation Events",
       "webhook_url": "https://your-server.com/webhooks/transformations",
       "site_ids": ["SITE_ID"],
       "events": [
         "transformation_asset_created"
       ]
     }
   }
   '
   
   

4. Listen for the transformation_asset_created event containing the transformation_run_id to confirm transformation completion.

5. Extract the values below from the webhook payload.

   ID	Use
   transformation_asset_id	ID used to manage the audio asset
   data.metadata.article_audio_variant_id	ID used to preview the audio asset prior to publishing

   
   
   JSON

   {
     "event": "transformation_asset_created", 
     "transformation_asset_id": "TRANSFORMATION_ASSET_ID",
     ...
     "data": {
       ...
       "metadata": {
         "article_audio_variant_id": "ARTICLE_AUDIO_VARIANT_ID", 
         ...
       }
     }
   }
   

6. Use the article_audio_variant_id to request the generated audio.

   cURL

   curl --request GET \
        --url 'https://api.jwplayer.com/v2/sites/{SITE_ID}/article_audio_variants/{ARTICLE_AUDIO_VARIANT_ID}/versions?page_length=1' \
        --header 'Authorization: <SECRET>' \
        --header 'accept: application/json'
   

7. Preview the audio by streaming or downloading it from the file_location.presigned_url.

   📘

   Each request generates a new presigned URL that expires 1 hour after creation.

8. Publish the audio by setting its status to published using the transformation_asset_id.

   cURL

   curl --request PATCH \
        --url https://api.jwplayer.com/v2/sites/{SITE_ID}/transformation_assets/{TRANSFORMATION_ASSET_ID} \
        --header 'Authorization: <SECRET>' \
        --header 'accept: application/json' \
        --header 'content-type: application/json' \
        --data '
   {
     "metadata": {
       "status": "published"
     }
   }
   '
   

Unpublish an asset

Unpublishing an asset removes it from delivery, making it unavailable to players and visitors while retaining the asset in your account.

Unpublish the audio using the transformation_asset_id.

curl --request PUT \
     --url https://api.jwplayer.com/v2/sites/{SITE_ID}/transformation_assets/{TRANSFORMATION_ASSET_ID}/unpublish \
     --header 'Authorization: <SECRET>' \
     --header 'accept: application/json'