---
title: "Compose a segmented video into a styled Short"
method: POST
path: "/api/v1/shorts-studio"
tags: ["Advanced"]
---

# Compose a segmented video into a styled Short

`POST /api/v1/shorts-studio`

## Request

- Base URL: `https://viewmax.studio`
- URL: `https://viewmax.studio/api/v1/shorts-studio`
- Auth: HTTP bearer

Advanced. `segmentationTaskId` and `transcriptTaskId` come from person-segmentation and Auto Captions tasks created in the ViewMax web app; the REST API cannot create them. Applies a fixed preset and returns an asynchronous task (202) or the existing task for a repeated `requestId` (200). Costs 1 credit. Poll with GET on this path.

## Request body

- ShortsStudioRequest
  - `requestId` string, uuid, required: Client-generated idempotency id. The same id with the same body returns the existing task; with a different body it returns 409 `request_conflict`.
  - `segmentationTaskId` string, required: Successful person-segmentation task created in the ViewMax web app.
  - `transcriptTaskId` string: Successful Auto Captions task created in the ViewMax web app for the same source video. Required when `words` is omitted.
  - `words` object[]: Word-level captions. Required when `transcriptTaskId` is omitted.
    - `text` string, required
    - `startMs` integer, required
    - `endMs` integer, required
    - `speakerId` string
  - `preset` 'comic_energy' | 'paper_collage' | 'product_clean'
  - `outputRatio` '9:16' | '16:9'
  - `backgroundColor` string
  - `includeSrt` boolean
  - `includeAss` boolean
  - `creditLimit` integer, required: Most credits this request may spend. The task costs 1 credit.

## Response `200`

Existing task for this `requestId`.

- object
  - `code` 0, required
  - `message` 'ok', required
  - `data` ShortsStudioTask, required
    - `id` string, required
    - `status` 'pending' | 'processing' | 'success' | 'failed' | 'canceled', required
    - `phase` 'queued' | 'rendering' | 'completed' | 'failed', required
    - `costCredits` integer, required
    - `preset` 'comic_energy' | 'paper_collage' | 'product_clean'
    - `outputRatio` '9:16' | '16:9'
    - `videoUrl` string, uri: Preview MP4, present on success.
    - `artifacts` object[]: Present on success.
      - `kind` 'video' | 'text', required
      - `role` 'preview' | 'srt' | 'ass', required
      - `url` string, uri, required
      - `contentType` 'video/mp4' | 'application/x-subrip' | 'text/x-ass', required
    - `error` 'processing_failed': Present when the task failed.

## Other responses

- `202`: Task accepted; poll it.
- `400`: `invalid_request`: body is not valid JSON or does not match the schema.
- `401`: `unauthorized`.
- `402`: `insufficient_credits`.
- `404`: `task_not_found`: segmentation or transcript task is not visible to this account.
- `409`: `request_conflict`: `requestId` was already used with a different body.
- `413`: `invalid_request`: body over 750,000 characters.
- `422`: `segmentation_not_ready`, `transcript_not_ready`, `transcript_mismatch`, `words_or_transcript_required`, or `credit_limit_exceeded`.
- `500`: `processing_failed`, including word timings that do not fit the source video.

---

[API](https://skmtc.dev/viewmax/apis/viewmax-studio-api.md) · [All operations](https://skmtc.dev/viewmax/apis/viewmax-studio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/viewmax/apis/viewmax-studio-api/revisions/c4f378e09f44?raw)