---
title: "Transform content"
method: PUT
path: "/v2/sites/{site_id}/transformation_transform/"
tags: ["transformations"]
---

# Transform content

`PUT /v2/sites/{site_id}/transformation_transform/`

Transforms content using a transformation agent in a single API call

This endpoint orchestrates the following operations:
1. Locates an existing project by `external_id`, or creates a new one
2. Creates an input asset from the provided content
3. Queues a transformation run for processing

**Input requirements:**
- `article_to_audio`, `article_to_podcast`, and `article_to_video` agents require `asset_type: "article"`
- `text_to_audio` agents require `asset_type: "text"`

## Path parameters

- `site_id` string, required — Unique identifier for a resource

## Request body

- TransformRequest — Request body for the transform endpoint
  - `external_id` string, required — Unique identifier for the project from your system, such as a CMS article ID If a project with the same value already exists, a new project will not be created.
  - `transformation_agent_id` string, required — Unique identifier for a resource
  - `input` union, required — Content to transform The schema is determined by the `asset_type` field.
    - ArticleInput — Metadata for article assets
      - `title` string, required — Article title
      - `description` string — Article summary or description
      - `source_url` string, uri — URL where the article is published
      - `thumbnail_url` string, uri — URL of the article thumbnail image
      - `external_id` string — External identifier from your system
      - `author` string — Author name
      - `published_at` string, date-time — Publication date and time
      - `content` string — Article body content
      - `asset_type` 'article', required
    - TextInput — Metadata for text assets
      - `title` string, required — Title of the text content
      - `content` string, required — Text content
      - `asset_type` 'text', required

## Response `201`

Transformation run successfully created

- TransformationRunResource — Single execution of a transformation agent
  - `id` string — Unique identifier for a resource
  - `site_id` string — Unique identifier for a resource
  - `type` 'transformation_run' — Resource type identifier
  - `created` string, date-time — Timestamp when the run was created
  - `transformation_type` 'article_to_audio' | 'article_to_podcast' | 'article_to_video' | 'text_to_audio' — Type of content transformation
  - `state` 'queued' | 'running' | 'awaiting_approval' | 'failed' | 'succeeded' — Processing state of the transformation run - `queued`: Run is waiting to be picked up for processing - `running`: Run is actively being processed - `awaiting_approval`: Run is paused on a human-in-the-loop review step - `failed`: Run encountered an error and did not complete - `succeeded`: Run completed successfully
  - `run_inputs` RunInputs — Inputs supplied to a transformation run
    - `input_asset_version_ids` ResourceId[], required — Default input asset version IDs for the run All input assets must belong to the same project. The project is derived from the input assets.
    - `step_inputs` StepInputOverride[] — Optional per-step input overrides Each entry targets a step type and an optional selector, and provides the input asset versions for matching steps. Steps without a matching override use `input_asset_version_ids`.
      - `step_type` string, required — Step type to which this override applies.
      - `selector` object — Optional additional matching criteria for the targeted step
      - `input_asset_version_ids` ResourceId[], required — Input asset version IDs to use for matching steps
      - `instruction_text` string — Optional free-text instruction passed to the step
  - `output_asset_version_ids` ResourceId[] — IDs of the output asset versions produced by this transformation
  - `transformation_config` object — Configuration snapshot used for this run
  - `error` object — Error details if the transformation failed
    - `code` string — Error code
    - `message` string — Human-readable error message
  - `started_at` string, date-time — Timestamp when processing started
  - `ended_at` string, date-time — Timestamp when processing completed
  - `metadata` object — No mutable fields for transformation runs
  - `relationships` object — Related resources
    - `project` object
      - `id` string — Unique identifier for a resource
    - `transformation_agent` object
      - `id` string — Unique identifier for a resource

## Other responses

- `400` — Bad Request The request either lacks certain attributes or contains malformed/invalid attributes.
- `404` — Not Found The requested asset could not be found.

---

[API](https://skmtc.dev/jwplayer/apis/management-api-v2.md) · [All operations](https://skmtc.dev/jwplayer/apis/management-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/jwplayer/management-api-v2/revisions/180db7cada27/schema)