Submit a video

Start a recognition job. Submit the video in one of two ways: upload the file directly, or reference a file you already uploaded to S3 with a presigned URL. Either way you get back a job_id to poll for the result.

Headers

Request

Send exactly one of file (a direct upload) or storage_key (a file already in S3). Either form also takes an optional channel_url — see Naming the creator’s channel.

File upload (multipart form data)

Best for small videos. The file is proxied through the API.

curl https://api.slipstreammusic.com/api/v4/video-recognition/ \
  -X POST \
  -H "Authorization: Bearer $PARTNER_API_KEY" \
  -F "file=@/path/to/clip.mp4"

Reference an uploaded file (JSON body)

Best for large videos. First call Get an upload URL, PUT the file to S3, then submit the returned storage_key here. The bytes never pass through the API.

curl https://api.slipstreammusic.com/api/v4/video-recognition/ \
  -X POST \
  -H "Authorization: Bearer $PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"storage_key": "video-recognition/8f3c...2a_clip.mp4"}'

Naming the creator’s channel

If the video is going on the creator’s own YouTube channel, ask for the channel while you have them: pass its URL as channel_url, in either request form, and the channel is added to their allowlist as part of the submit. Any of these resolve:

The scheme is optional, and a tab suffix such as /videos is ignored. An empty or null value is the same as leaving the field out.

curl https://api.slipstreammusic.com/api/v4/video-recognition/ \
  -X POST \
  -H "Authorization: Bearer $PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-User-ID: creator-4821" \
  -d '{"storage_key": "video-recognition/8f3c...2a_clip.mp4", "channel_url": "youtube.com/@GoogleDevelopers"}'

The add follows the same rules as Add a channel: the channel lands on the end user named by X-User-ID, or on your own account without it; a creator we have not seen before is registered by it; and a channel can be on one allowlist only. There is no confirmation step, so ask the creator for their own channel: a video link resolves to whichever channel published it, and a clip they did not make would put someone else’s channel on their allowlist. Remove undoes it.

Naming a channel needs channel management enabled on your account, the same grant the channel endpoints use. An add made this way is charged to your channel-management allowance exactly as a call to Add a channel would be, and refunded when it is refused; the submit itself still counts against the AudioVerify quota. A used-up allowance refuses the add, not the check: it comes back as channel.status error.

Response (201 Created)

{
  "job_id": "7b2c1e8a-0f4d-4a2b-9c11-7f5a2d9e3c10",
  "status": "queued",
  "track": null
}

The track is always null here, and there are no segments yet. Poll GET /api/v4/video-recognition/{job_id}/ until status is completed to get the result.

When you sent a channel_url, the body also carries channel, and every poll of the job repeats it:

{
  "job_id": "7b2c1e8a-0f4d-4a2b-9c11-7f5a2d9e3c10",
  "status": "queued",
  "track": null,
  "channel": {
    "status": "added",
    "id": "9b5c3d2e-0a8e-4b7c-8c4d-2f9e5f6b8d7c",
    "channel_id": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "name": "Google for Developers",
    "thumbnail_url": "https://yt3.ggpht.com/..."
  }
}

channel.status is one of added, already_added, not_resolved or error; the field is absent when no channel was named. See The ChannelResult object for what each state means and what to do with it.

Errors

Rate limits

Only this submit endpoint is metered. Polling a job and requesting an upload URL are free. Each submit counts against the daily AudioVerify quota configured for your partnership.

When you exceed it, the submit returns 429 before any recognition runs, with the cap, your current usage, and when the window resets:

{
  "detail": "You have reached your daily AudioVerify limit.",
  "scope_code": "compliance_check",
  "window": "daily",
  "cap": 5000,
  "used": 5000,
  "resets_in": "7 hours",
  "resets_at": "2026-07-09T00:00:00+00:00"
}

Back off until resets_at, then retry.