API reference
Complete a media upload
Turns the upload into a vault item and starts moderation. Image / audio: the parts are joined and stored with their metadata removed. Video: the finished tus upload is registered.
View as MarkdownUpdated Oct 31, 2026
POST
/api/external/v1/media/uploads/{id}/completealso served at /api/external/media/uploads/{id}/completeNewTurns the upload into a vault item and starts moderation. Image / audio: the parts are joined and stored with their metadata removed. Video: the finished tus upload is registered.
Idempotent: completing a completed session returns the same body, so retry freely. The item starts PENDING; poll GET the session for moderationStatus, and for a video video-status for transcoding.
For a video, 409 upload_not_finished means retry: the CDN can lag a few seconds after your tus client reports done, so back off (2s, 5s, 10s, 30s) and call again.
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}/media/uploads/{id}/complete — 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.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The upload id from POST /api/external/v1/media/uploads. |
Responses
200Completed (or already completed).
| Name | Type | Description | ||||||
|---|---|---|---|---|---|---|---|---|
id | string | Upload id. | ||||||
kind | string | What you are uploading. One of: image, video, audio | ||||||
status | string | uploading until you complete it; processing while a complete runs; completed once the vault item exists.One of: uploading, processing, completed, failed, expired | ||||||
fileName | string | The file name, stored on the vault item. | ||||||
contentType | string | The stored content type. | ||||||
sizeBytes | integer | The declared size. | ||||||
folderId | string | null | The vault folder the item goes in. | ||||||
partSize | integer | null | Image / audio: bytes per part (the last part is the remainder). Null for video. | ||||||
totalParts | integer | null | Image / audio: number of parts. Null for video. | ||||||
receivedParts | integer[] | null | Part numbers received so far. | ||||||
missingParts | integer[] | null | Part numbers still to upload. | ||||||
vaultItemId | string | null | The vault item, once completed. | ||||||
moderationStatus | string | null | The vault item’s moderation status, once completed. One of: PENDING, APPROVED, FLAGGED, REJECTED | ||||||
bunnyStreamId | string | null | Video: the Stream video id — poll [video-status](/developers/reference/video-status) with it. | ||||||
error | object | null | { code, message } when the upload failed or expired.Show child attributes
| ||||||
expiresAt | string | Upload the parts (or the tus bytes) and complete before this. Format: date-time | ||||||
createdAt | string | When the session was opened. Format: date-time | ||||||
completedAt | string | null | When it completed. Format: date-time |
Example response
{
"id": "mu_3f9c1a7be0d24c55a1e8b6f2",
"kind": "image",
"status": "completed",
"fileName": "beach.jpg",
"contentType": "image/jpeg",
"sizeBytes": 7904267,
"folderId": null,
"partSize": 3145728,
"totalParts": 3,
"receivedParts": [
1,
2,
3
],
"missingParts": [],
"vaultItemId": "clxv9z8y70003item",
"moderationStatus": "PENDING",
"bunnyStreamId": null,
"error": null,
"expiresAt": "2026-10-31T18:00:00.000Z",
"createdAt": "2026-10-31T10:00:00.000Z",
"completedAt": "2026-10-31T10:00:41.000Z"
}Errors
| Status | Body | When |
|---|---|---|
| 401 | {"error":"Unauthorized","code":"unauthorized"} | Missing or invalid API key. |
| 404 | {"error":"Upload not found","code":"upload_not_found"} | Unknown id, or an upload of another account. |
| 409 | {"error":"Upload the missing parts first: 3","code":"missing_parts","missingParts":[3]} | Image / audio: parts are missing. Upload them and complete again. |
| 409 | {"error":"The video has not finished uploading — retry in a few seconds","code":"upload_not_finished"} | Video: the CDN has not received all the bytes yet — back off and retry. |
| 409 | {"error":"This upload is already being completed — poll GET for its status","code":"complete_in_progress"} | Another complete call is running for this session. |
| 409 | {"error":"File too large. Max 30MB for image.","code":"upload_failed","reason":"file_too_large"} | The session already failed — start a new one. |
| 410 | {"error":"This upload session has expired — start a new one","code":"upload_expired"} | Past `expiresAt`. |
| 413 | {"error":"Video too large. Max 500MB.","code":"file_too_large"} | The stored file is over the limit; the upload is discarded. |
| 415 | {"error":"Unsupported image format. Please upload a JPEG, PNG, WebP, GIF, HEIC or AVIF.","code":"UNSUPPORTED_FORMAT"} | Image / audio: we cannot remove the file’s metadata safely (also 422 MALFORMED / UNSANITISABLE), so it is not stored. |
| 500 | {"error":"Could not complete the upload — retry","code":"complete_failed"} | Unexpected failure — the session goes back to `uploading`; retry. |
| 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/media/uploads/$VAULT_ITEM_ID/complete" \
-H "Authorization: Bearer $DROPFANS_API_KEY"const vaultItemId = '…'; // from an earlier response
const res = await fetch(`https://www.dropfans.io/api/external/v1/media/uploads/${vaultItemId}/complete`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,
},
});
console.log(await res.json());import os
import requests
vault_item_id = "…" # from an earlier response
res = requests.post(
f"https://www.dropfans.io/api/external/v1/media/uploads/{vault_item_id}/complete",
headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
)
print(res.json())Questions? [email protected]