API reference

Check video transcoding status (batch)

Transcoding status + duration for a batch of video GUIDs (`bunnyStreamId` values from your vault items).

View as MarkdownUpdated Aug 19, 2026

POST/api/external/v1/vault/video-statusalso served at /api/external/vault/video-status

Transcoding status + duration for a batch of video GUIDs (bunnyStreamId values from your vault items).

A freshly uploaded video is not forwardable or playable until isReady — poll this while isProcessing. Reasonable interval: every 15–30 seconds while you wait on a specific video.

Silent truncation and omission

At most 50 ids are processed per call — extras are dropped without an error, so chunk larger lists. Ids you don't own, and ids whose lookup errored, are omitted from the response rather than reported: treat a missing key as "not ready".

Authentication

Send the creator's API key as a bearer token: Authorization: Bearer dpfn_…. See Authentication & API keys.

For a creator you manage or onboarded

POST /api/external/v1/creators/{creatorId}/vault/video-status — an agency's own key for a creator or AI persona it manages (needs canManageVault), or your app owner's own key for an account your app onboarded. The X-Dropfans-Account header still works but is deprecated. See Acting for a creator.

Request body

Content type: application/json

Name	Type	Required	Description
`videoIds`	string[]	Required	Stream GUIDs to check (≤50 — extras silently dropped). Non-strings are filtered out; an empty array returns {"statuses":{}}. Max items: 50

Check two videos

{
  "videoIds": [
    "c2f7f9e2-1111-4222-b333-4d55e6f7a8b9",
    "0f3d9a11-2222-4333-a444-5e66f7a8b9c0"
  ]
}

Responses

200Status map keyed by the GUIDs you sent (unresolvable ids omitted).

Name Type Description

statuses

VideoStatusMap

GUID → status.

Show child attributes

{videoId}

object

Keyed by the Bunny Stream GUIDs you sent. Ids you don’t own, and ids whose Bunny lookup errored, are OMITTED (not reported as failed) — treat a missing key as "still gated".

Show child attributes

`isReady`	boolean	Transcoding finished — the video is playable and forwardable.
`isProcessing`	boolean	Still transcoding — poll again later.
`isFailed`	boolean	Encoding failed — re-upload.
`length`	integer	Duration in seconds, once known.

Example response

{
  "statuses": {
    "c2f7f9e2-1111-4222-b333-4d55e6f7a8b9": {
      "isReady": true,
      "isProcessing": false,
      "isFailed": false,
      "length": 74
    },
    "0f3d9a11-2222-4333-a444-5e66f7a8b9c0": {
      "isReady": false,
      "isProcessing": true,
      "isFailed": false
    }
  }
}

Errors

Status	Body	When
400	`{"error":"Invalid JSON body"}`	The body is not valid JSON.
401	`{"error":"Unauthorized","code":"unauthorized"}`	Missing or invalid API key.
400	`{"error":"X-Dropfans-Account must be an account id (from GET /api/external/agency/creators), not a username.","code":"invalid_account_header"}`	`X-Dropfans-Account` is not an account id.
400	`{"error":"X-Dropfans-Account names a different account than the path — send one or the other.","code":"account_mismatch"}`	Called under /v1/creators/{creatorId}/ with an `X-Dropfans-Account` naming another account.
403	`{"error":"This key cannot act for that account.","code":"account_not_managed"}`	The creator in the path (or `X-Dropfans-Account`) is one this key cannot act for: no ACCEPTED management by your agency and not an account your app onboarded (or it no longer holds a key bound to your app), a key minted for one creator, or someone is suspended, banned or deleted. An unknown id gets the same answer.
403	`{"error":"The agency does not have permission for this on that account.","code":"permission_denied","permission":"canManageVault"}`	For a managed creator: the agency lacks `canManageVault` on that account.
403	`{"error":"This app does not have the vault API category enabled. Contact support to enable it.","code":"api_category_disabled","category":"vault"}`	Your app has the Vault [API category](/developers/concepts/api-categories) switched off.

Rate limiting

Every response carries the X-RateLimit-Tier header and, on limited tiers, the per-minute and per-day trios — read X-RateLimit-Remaining and X-RateLimit-Reset instead of hardcoding limits. Details in Rate limits.

Code samples

curl -X POST "https://www.dropfans.io/api/external/v1/vault/video-status" \
  -H "Authorization: Bearer $DROPFANS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "videoIds": [
    "c2f7f9e2-1111-4222-b333-4d55e6f7a8b9",
    "0f3d9a11-2222-4333-a444-5e66f7a8b9c0"
  ]
}'

const res = await fetch(`https://www.dropfans.io/api/external/v1/vault/video-status`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "videoIds": [
      "c2f7f9e2-1111-4222-b333-4d55e6f7a8b9",
      "0f3d9a11-2222-4333-a444-5e66f7a8b9c0"
    ]
  }),
});
console.log(await res.json());

import os
import requests

res = requests.post(
    "https://www.dropfans.io/api/external/v1/vault/video-status",
    headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
    json={
        "videoIds": [
            "c2f7f9e2-1111-4222-b333-4d55e6f7a8b9",
            "0f3d9a11-2222-4333-a444-5e66f7a8b9c0",
        ],
    },
)
print(res.json())

← Previous

Finish a video upload (step 3 of 3)

Start a media upload session

Questions? support@dropfans.io