agent reference

Register a YouTube URL. The server probes title and duration via yt-dlp.

BODY

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}

RESPONSE

{
  "streamId": "str_a1b2c3d4",
  "url": "https://...",
  "title": "Stream title",
  "durationSec": 7444
}

CURL

curl -X POST http://localhost:3000/api/v1/streams \
  -H "Authorization: Bearer <spacialclipAgentToken>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=..."}'

Ask spacialclip to suggest interesting moments from captions, engagement metadata, or fallback spacing.

BODY

{
  "streamId": "str_a1b2c3d4",
  "count": 3,
  "clipLength": 45
}

RESPONSE

{
  "streamId": "str_a1b2c3d4",
  "durationSec": 7444,
  "moments": [
    { "start": 1240, "end": 1285, "caption": "Best transcript hook...", "score": 0.82 }
  ],
  "transcriptCues": 42,
  "hotspots": 0
}

CURL

curl -X POST http://localhost:3000/api/v1/moments \
  -H "Authorization: Bearer <spacialclipAgentToken>" \
  -H "Content-Type: application/json" \
  -d '{"streamId":"str_a1b2c3d4","count":3}'

Queue a clip. Returns 202; poll GET /api/v1/clips/:id for status.

BODY

{
  "streamId": "str_a1b2c3d4",
  "start": 1240,
  "end": 1270,
  "caption": "Insane clutch"
}

RESPONSE

{
  "id": "clp_xyz...",
  "streamId": "str_a1b2c3d4",
  "start": 1240,
  "end": 1270,
  "caption": "Insane clutch",
  "status": "queued"
}

CURL

curl -X POST http://localhost:3000/api/v1/clips \
  -H "Authorization: Bearer <spacialclipAgentToken>" \
  -H "Content-Type: application/json" \
  -d '{"streamId":"str_a1b2c3d4","start":1240,"end":1270,"caption":"Insane clutch"}'

List clips, newest first.

RESPONSE

{
  "clips": [ { "id": "clp_...", "status": "ready", ... } ]
}

CURL

curl http://localhost:3000/api/v1/clips \
  -H "Authorization: Bearer <spacialclipAgentToken>"

Poll a single clip. Status: queued → downloading → cutting → ready (or failed).

RESPONSE

{
  "id": "clp_xyz",
  "status": "ready",
  "downloadUrl": "/api/v1/clips/clp_xyz/file",
  "reelMetadata": {
    "title": "Shorts-ready title",
    "description": "YouTube description...",
    "tags": ["shorts", "highlight"],
    "overlayTitle": "On-video title",
    "shortCaption": "Social caption"
  }
}

CURL

curl http://localhost:3000/api/v1/clips/clp_xyz \
  -H "Authorization: Bearer <spacialclipAgentToken>"

Download the rendered MP4. Only available once status === "ready".

RESPONSE

(binary video/mp4)

CURL

curl -O -J http://localhost:3000/api/v1/clips/clp_xyz/file \
  -H "Authorization: Bearer <spacialclipAgentToken>"

Upload the rendered reel to YouTube using generated metadata. Requires YouTube OAuth env vars.

BODY

{
  "title": "Optional override",
  "description": "Optional override",
  "tags": ["optional", "override"]
}

RESPONSE

{ "ok": true, "platform": "youtube", "videoId": "...", "url": "..." }

CURL

curl -X POST http://localhost:3000/api/v1/clips/clp_xyz/post \
  -H "Authorization: Bearer <spacialclipAgentToken>" \
  -H "Content-Type: application/json" \
  -d '{"title":"Insane clutch"}'

Remove a clip from the store. Local files are kept on disk.

RESPONSE

{ "ok": true }

CURL

curl -X DELETE http://localhost:3000/api/v1/clips/clp_xyz \
  -H "Authorization: Bearer <spacialclipAgentToken>"