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/reopen-project-upload.md, and every docs URL returns Markdown when requested with Accept: text/markdown.

Get new upload instructions
Returns fresh multipart upload instructions (with a new 24-hour upload_token) for a project whose file has not arrived yet.
POST https:/
- Key scope:
projects:write - Auth header:
Authorization: Bearer <apiKey> - Body: None
Request
Pass project_id in the path; send no body (or {}).
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
#project_id | string | Required: Yes | Unique identifier of the project. |
Headers
| Field | Type | Required | Description |
|---|---|---|---|
#Diffio-End-User | string | Required: No | Optional 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.reopen_upload(
"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
)Response
Returns the project with renewed upload descriptors pointing to the same destination.
Success: 200OK.
Response fields
| Field | Type | Present | Description |
|---|---|---|---|
#id | string | Always | Unique project identifier (UUID). |
#object | string | Always | Resource type, always "project".project |
#status | string | Always | Upload and preparation state: awaiting_upload until bytes arrive, preparing while media is probed, ready when ready to restore, or failed.awaiting_uploadpreparingreadyfailed |
#upload | object | null | Always | Multipart upload instructions for sending the file to the media edge, or null on an idempotent replay after the upload has arrived.Fields below |
upload 11 fields
| Field | Type | Present | Description |
|---|---|---|---|
#upload. | string | Always | Upload session identifier (api-{project_id}). |
#upload. | string | Always | Origin URL of the media upload edge (https://media.diffio.io). |
#upload. | string | Always | Signed bearer token sent as Authorization: Bearer <token> on every upload edge request. |
#upload. | integer | Always | Required byte length for every upload part except the last (33554432, 32 MiB). |
#upload. | integer | Always | Maximum total upload size in bytes (2147483648, 2 GB). |
#upload. | string | Always | ISO 8601 UTC timestamp when upload_token expires (24 hours after minting); renew via POST /projects/{project_id}/upload. |
#upload. | object | Always | Pre-built HTTP request descriptors for the multipart upload (start, part, complete, abort). |
#upload. | object | Always | Descriptor (method, url, headers, body, returns, description) called once first to obtain uploadId. |
#upload. | object | Always | Descriptor called once per part (numbered from 1) with raw bytes as the PUT body; save each returned etag. |
#upload. | object | Always | Descriptor called once after all parts finish, sending uploadId and the ordered parts array (partNumber, etag). |
#upload. | object | Always | Optional descriptor to discard uploaded parts for an unfinished uploadId. |
Other response fields16 fields
| Field | Type | Present | Description |
|---|---|---|---|
#file_name | string | null | Always | Recording filename as sent at creation, or null. |
#content_type | string | null | Always | MIME type sent at creation (application/octet-stream when none was sent), or null. |
#size_bytes | integer | null | Always | File size in bytes: the uploaded byte count once the upload arrives, before that the size_bytes sent at creation; null when unknown. |
#duration_seconds | number | null | Always | Recording duration in seconds once status is ready, or null while awaiting upload or preparing. |
#has_video | boolean | Always | True when the recording has video: inferred from content_type or the file name until the upload is probed, then from the file itself. |
#end_user | string | null | Always | End-user identifier from the Diffio-End-User header at creation, or null for account-level projects. |
#metadata | object | Always | Key-value string map saved with the project ({} when none was supplied). |
#generation_count | integer | Always | Total number of generations created for this project. |
Show all 16 fields (8 more)
| Field | Type | Present | Description |
|---|---|---|---|
#video_preview_status | string | null | Always | State of a video project's picture-only HLS stream (video_hls): preparing, ready, or failed; null for audio projects.preparingreadyfailed |
#share_id | string | null | Always | Public 17-character share identifier while a share is published, or null when unshared. |
#latest_generation | object | null | Always | Newest Generation object on this project, or null when no generation exists yet. |
#created_at | string | null | Always | ISO 8601 UTC timestamp when the project was created, or null. |
#updated_at | string | null | Always | ISO 8601 UTC timestamp when the project last changed, or null. |
#error | object | null | Always | Failure details when status is failed, or null otherwise. |
#error. | string | Always | Stable snake_case project failure code (media_processing_failed or project_failed). |
#error. | string | Always | Human-readable explanation of why the upload could not be prepared. |
Response 200OK.
{
"id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
"object": "project",
"status": "awaiting_upload",
"upload": {
"upload_token": "v1.REDACTED",
"part_size_bytes": 33554432,
"expires_at": "2026-11-14T00:33:21.812909Z",
"requests": {
"start": {
"method": "POST",
"url": "https://media.diffio.io/v1/uploads/start",
"headers": {
"Authorization": "Bearer v1.REDACTED"
},
"body": null,
"returns": [
"uploadId",
"partSizeBytes",
"maxBytes"
],
"description": "Once, first. Keep uploadId for the other requests."
}
}
}
}Return codes
200OK.Returns the project with renewed 24-houruploadinstructions.400Bad request.Malformed JSON body, orDiffio-End-Userexceeds 128 characters.invalid_jsoninvalid_header403Forbidden: the key lacks permission.Key is inactive or lacksprojects:write.permission_denied404Not found.No project with thatproject_idexists for this account and end user.project_not_found409Conflict: see error.code for which one.The project's file has already arrived, withdetails.project_statusreporting its current status.upload_already_received401Unauthorized: the API key is missing or invalid.405Client error.Same on every endpoint401Unauthorized: 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": {
"code": "invalid_api_key",
"message": "Invalid API key.",
"request_id": "dead773b60e148fd9e22d680a22fa701"
}
}Notes
- Only projects in
status: "awaiting_upload"accept new upload instructions; once the upload arrives, create a new project to upload a different file. - Both SDKs call this from
projects.upload(...)when you pass a project id instead of the created project; the Python SDK also calls it whenupload.expires_atis less than 60 seconds away.