Media Processing API Reference

Media processing

Media processing is exposed under /media. A media input may be retained as an asset so it can be analyzed more than once, but callers do not need to model the underlying storage or processing implementation.

Addressing and authentication

Use either the node alias or the node ID. The addressed node determines the owning account boundary.

Authorization: Bearer $API_KEY

Anonymous access is not supported. A node-scoped key cannot cross node or tenant boundaries.

Capability gates

Disabled capabilities return 404 so capability existence is not disclosed.

• media.audio and media.audio.transcribe gate transcription.
• media.video and media.video.analyze gate durable video processing.

Route overview

Every route also has a node-ID form: /nodes/{nodeId}/media/....

One-off audio transcription

Use POST /media/audio/transcribe when you want a direct response and do not need a durable input or analysis record.

curl -X POST \
  https://my-node.interlocute.ai/media/audio/transcribe \
  -H "Authorization: Bearer $API_KEY" \
  -F "audio=@recording.mp3" \
  -F "language=en" \
  -F "format=segments"

Create a media input

Upload bytes with only file and optional displayName. Do not send tenant or node association fields.

curl -X POST \
  https://my-node.interlocute.ai/media/assets/upload \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@reflection.mp4" \
  -F "displayName=Weekly reflection"

Or reference an HTTPS URL:

curl -X POST \
  https://my-node.interlocute.ai/media/assets/from-url \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.test/reflection.mp4", "displayName": "Weekly reflection" }'

{
  "assetId": "asset_...",
  "kind": "video",
  "displayName": "Weekly reflection",
  "contentType": "video/mp4",
  "hasVideoTrack": true,
  "hasAudioTrack": true,
  "durationSeconds": 412.4,
  "createdAt": "2026-09-11T08:00:00Z"
}

Profiles and analysis

Ask the input for its available profiles. Audio-only inputs expose speech. Video inputs expose speech, visual, insights, and speech+visual when enabled.

curl https://my-node.interlocute.ai/media/assets/asset_.../profiles \
  -H "Authorization: Bearer $API_KEY"

speech+visual is one canonical analysis request, not two hidden processing jobs.

curl -X POST https://my-node.interlocute.ai/media/assets/asset_.../analyze \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profileId": "speech+visual" }'

{
  "recordId": "record_...",
  "requestedProfileId": "speech+visual",
  "status": "submitted"
}

Poll and read typed results

curl https://my-node.interlocute.ai/media/records/record_.../status \
  -H "Authorization: Bearer $API_KEY"

{
  "recordId": "record_...",
  "assetId": "asset_...",
  "requestedProfileId": "speech+visual",
  "status": "completed",
  "progressPercent": null
}

After completion, payload.video contains the typed video analysis result. Internal source URLs, job identifiers, and renditions are not part of the public contract; the public input reference is media://asset/{assetId}.

curl https://my-node.interlocute.ai/media/records/record_.../payload \
  -H "Authorization: Bearer $API_KEY"

Retry and delete

Polling an active or completed record is idempotent. Retrying a terminal failure submits a new analysis for the same asset and preserves the failed record as history.

curl -X DELETE "https://my-node.interlocute.ai/media/assets/asset_...?deleteRecords=true" \
  -H "Authorization: Bearer $API_KEY"

Remote cleanup is only guaranteed when the underlying lifecycle explicitly supports it.