---
name: "cli-anything-transcode-api-v2"
description: "CLI for transcode_api_v2 — submit/track video transcoding tasks, call AI media ops (VideoClip, AudioExtract, WaterMark, etc.), manage templates, and monitor live-stream jobs via the /intf.php API."
triggers:
  - "transcode video"
  - "submit transcoding task"
  - "task status"
  - "media clip"
  - "video processing api"
  - "transcode_api_v2"
  - "template transcoding"
  - "live stream task"
---

# cli-anything-transcode-api-v2

CLI harness for **transcode_api_v2** — a PHP video/audio transcoding API. Wraps
`POST /intf.php?method=Module.Action` for all task management, AI media processing,
template management, and monitoring operations.

## Installation

```bash
cd agent-harness
pip install -e .
```

## Configuration

```bash
export TRANSCODE_API_BASE_URL=http://your-server
export TRANSCODE_API_SNAME=my_service
export TRANSCODE_API_SECRET=signing_secret

# Development — no live server needed
export TRANSCODE_API_MOCK=1
```

## Base Syntax

```
cli-anything-transcode-api-v2 [--base-url URL] [--sname NS] [--secret S] [--json] [--repl] \
    <group> <subcommand> [OPTIONS]
```

- `--json` — emit machine-readable JSON on stdout
- `--repl` — launch interactive REPL
- `--save-as ALIAS` — store result for later reference

## Command Groups

### task — VOD transcoding (Main module)

```bash
cli-anything-transcode-api-v2 task add --service <svc> --args '<JSON>' [--bucket B] [--weight low|normal|high]
cli-anything-transcode-api-v2 task stop <tid>
cli-anything-transcode-api-v2 task get <tid>
cli-anything-transcode-api-v2 task get-many <tid1> <tid2> ...
cli-anything-transcode-api-v2 task wait <tid> [--timeout 300] [--interval 5]
```

### media — AI/advanced media (Media module)

```bash
cli-anything-transcode-api-v2 media actions
cli-anything-transcode-api-v2 media call <ACTION> '<JSON_BODY>'
cli-anything-transcode-api-v2 media get <tid>
cli-anything-transcode-api-v2 media stop <tid>
```

Available actions: Snapshot, AudioExtract, VideoClip, ConcatVideo, PicToVideo, WaterMark,
Subtitles, AutoSubtitles, ContentSummary, VideoAddBgm, VideoStretch, AudioConcat,
VideoCutGif, VideoCutByRatio, VideoFade, VideoAddMask, ImageEnlargementToVideo,
MediaAdjustVolume, VideoAddDub, VideoMute, AudioCutByTime, VideoReverse, VideoRotate,
ImageToVideo, VideoAddAudio, MediaSeparatiVoice, VideoQualityAssessment, AudioStretch,
AIRemoveWaterMark, PicToSpecialEffectsVideo.

### template — Reusable templates

```bash
cli-anything-transcode-api-v2 template list --eqid <eqid>
cli-anything-transcode-api-v2 template get --eqid <eqid> <id>
cli-anything-transcode-api-v2 template add --eqid <eqid> --uqid <uqid> --name <n> --args '<JSON>'
cli-anything-transcode-api-v2 template delete --eqid <eqid> <id>
```

### template-task — Template-based tasks

```bash
cli-anything-transcode-api-v2 template-task list --eqid <eqid>
cli-anything-transcode-api-v2 template-task get --eqid <eqid> <id>
cli-anything-transcode-api-v2 template-task presign <filename>
cli-anything-transcode-api-v2 template-task download-url <filename>
```

### live — Live-stream tasks

```bash
cli-anything-transcode-api-v2 live list
cli-anything-transcode-api-v2 live get <tid>
cli-anything-transcode-api-v2 live stop --cid <cid> --tid <tid>
```

### monitor — Health check (no auth)

```bash
cli-anything-transcode-api-v2 monitor health
```

### session — In-memory result store

```bash
cli-anything-transcode-api-v2 session list
cli-anything-transcode-api-v2 session get <alias>
cli-anything-transcode-api-v2 session clear
```

## Output Format

**Human** (default):
```
  tid: 12345
  status: 1 (done)
  progress: 100
```

**JSON** (`--json`):
```json
{"tid": 12345, "status": 1, "progress": 100, "errno": 0}
```

**Error** (`--json`):
```json
{"errno": 120001, "errmsg": "task not found"}
```

## Common Workflows

### Submit and poll a transcoding job

```bash
# Submit
cli-anything-transcode-api-v2 --json task add \
  --service transcode \
  --args '{"input":"https://cdn.example.com/source.mp4","output":"mp4"}' \
  --save-as job1

# Poll until done (up to 10 minutes)
cli-anything-transcode-api-v2 task wait 12345 --timeout 600
```

### Call an AI media operation

```bash
cli-anything-transcode-api-v2 --json media call VideoClip \
  '{"sname":"my_service","args":{"video_url":"https://...","start":5,"end":30}}'
# Returns: {"tid": 99001}
```

### REPL session

```
$ cli-anything-transcode-api-v2 --repl
transcode-api-v2> monitor health
transcode-api-v2> task get 12345 --save-as result
transcode-api-v2> session get result
transcode-api-v2> exit
```

## Agent Guidance

1. Always use `--json` for programmatic output.
2. `"errno": 0` means success; non-zero is an error — read `"errmsg"`.
3. Task status: 0=queued, 1=done, 2=failed, 3=sending, 6=processing.
4. Use `task wait` to block until a task completes rather than polling manually.
5. Use `--save-as` to chain results without parsing JSON between steps.
6. Use `TRANSCODE_API_MOCK=1` to test workflows without a live server.
7. The `media call` command accepts any `Media.*` action — run `media actions` for the full list.
