Skip to content

For AI agents: every API docs page in one plain-text file is at /docs/llms-full.txt, and the documentation index is at /llms.txt. This page is available as Markdown at https://diffio.ai/docs/api-reference/complete-project-upload.md, and every docs URL returns Markdown when requested with Accept: text/markdown.

Complete a project's upload

Optional call after upload.requests.complete that probes and prepares the uploaded recording immediately, starting any queued generation right away.

POST https://api.diffio.ai/v2/projects/{project_id}/upload/complete

  • Key scope: projects:write
  • Auth header:Authorization: Bearer <apiKey>
  • Body: None
  1. POST /projects
  2. uploads/start
  3. uploads/parts
  4. uploads/complete
  5. upload/complete
The HTTP upload sequence, call by call
  1. POST/projectsid and upload
  2. POSTupload.requests.start.urluploadId
  3. PUTupload.requests.part.url (one per part)etag per part
  4. POSTupload.requests.complete.urlsizeBytes, etag
  5. POST/projects/{project_id}/upload/completeoptional; status preparing or ready

Every edge call: Authorization: Bearer {upload_token}Parts ≤ 32 MiB (part_size_bytes, numbered from 1)

Request

Pass project_id in the path after all parts and upload.requests.complete have succeeded; takes no body.

Path parameters

FieldTypeRequiredDescription
#project_idstringRequired: YesUnique identifier of the project.

Headers

FieldTypeRequiredDescription
#Diffio-End-UserstringRequired: NoOptional end-user identifier (up to 128 characters). Scopes the request to that end user's projects; omit to act across the whole account.

Request

import os
from diffio import DiffioClient

key = os.environ["DIFFIO_API_KEY"]
client = DiffioClient(api_key=key)

project = client.projects.complete_upload(
    "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
)

Response

Returns the updated project (preparing, ready, or failed), including latest_generation.

Success: 200OK.

Response fields

FieldTypePresentDescription
#idstringAlwaysUnique project identifier (UUID).
#objectstringAlwaysResource type, always "project".project
#statusstringAlwaysUpload and preparation state: awaiting_upload until bytes arrive, preparing while media is probed, ready when ready to restore, or failed.awaiting_uploadpreparingreadyfailed
#file_namestring | nullAlwaysRecording filename as sent at creation, or null.
#content_typestring | nullAlwaysMIME type sent at creation (application/octet-stream when none was sent), or null.
#size_bytesinteger | nullAlwaysFile size in bytes: the uploaded byte count once the upload arrives, before that the size_bytes sent at creation; null when unknown.
#duration_secondsnumber | nullAlwaysRecording duration in seconds once status is ready, or null while awaiting upload or preparing.
#has_videobooleanAlwaysTrue when the recording has video: inferred from content_type or the file name until the upload is probed, then from the file itself.
Show all 19 fields (11 more)
FieldTypePresentDescription
#end_userstring | nullAlwaysEnd-user identifier from the Diffio-End-User header at creation, or null for account-level projects.
#metadataobjectAlwaysKey-value string map saved with the project ({} when none was supplied).
#generation_countintegerAlwaysTotal number of generations created for this project.
#video_preview_statusstring | nullAlwaysState of a video project's picture-only HLS stream (video_hls): preparing, ready, or failed; null for audio projects.preparingreadyfailed
#share_idstring | nullAlwaysPublic 17-character share identifier while a share is published, or null when unshared.
#latest_generationobject | nullAlwaysNewest Generation object on this project, or null when no generation exists yet.
#created_atstring | nullAlwaysISO 8601 UTC timestamp when the project was created, or null.
#updated_atstring | nullAlwaysISO 8601 UTC timestamp when the project last changed, or null.
#errorobject | nullAlwaysFailure details when status is failed, or null otherwise.
#error.codestringAlwaysStable snake_case project failure code (media_processing_failed or project_failed).
#error.messagestringAlwaysHuman-readable explanation of why the upload could not be prepared.

Response 200OK.

Successful response
{
  "id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
  "object": "project",
  "status": "ready",
  "file_name": "interview.mp3",
  "content_type": "audio/mpeg",
  "size_bytes": 510957,
  "duration_seconds": 31.9,
  "has_video": false,
  "end_user": "customer-mwe8tm1g",
  "metadata": {
    "order_id": "1042"
  },
  "generation_count": 0,
  "video_preview_status": null,
  "latest_generation": null,
  "share_id": null,
  "created_at": "2026-11-13T00:33:21.812909Z",
  "updated_at": "2026-11-13T00:33:26.311000Z",
  "error": null
}

Return codes

  • 200OK.Upload verified and the updated project is returned.
  • 400Bad request.Malformed JSON body, or Diffio-End-User exceeds 128 characters. invalid_jsoninvalid_header
  • 403Forbidden: the key lacks permission.Key is inactive or lacks projects:write. permission_denied
  • 404Not found.No project with that project_id exists for this account and end user. project_not_found
  • 409Conflict: see error.code for which one.Upload bytes have not finished landing in storage yet. upload_missing
  • 413Payload too large.Stored upload exceeds the 2 GB (2,147,483,648 bytes) limit. upload_too_large
  • 503Service unavailable.Storage service temporarily unavailable while verifying the upload (code unavailable).
  • 401Unauthorized: the API key is missing or invalid.405Client error.Same on every endpoint
    • 401Unauthorized: the API key is missing or invalid. Missing API key (code missing_api_key), or invalid API key (code invalid_api_key).
    • 405Client error. HTTP method not supported on this path; check the Allow header (code method_not_allowed).

Example error response

Errors are JSON: an error object with code, message and request_id. An unrecognized key returns 401Unauthorized: the API key is missing or invalid.:

Error response
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key.",
    "request_id": "dead773b60e148fd9e22d680a22fa701"
  }
}

Notes

  • Calling this endpoint is optional: the media upload edge notifies Diffio automatically about 30 seconds after upload.requests.complete finishes.
  • Safe to repeat; calling it again on an already ready project returns the current project unchanged.
  • If probing reveals an unreadable or unsupported media container, the call returns 200 with status: "failed" and error.code: "media_processing_failed".

Report an issue with this page