API reference

Create project

Create a project and return a signed upload URL. Review Diffio API behavior, response fields, setup details, and production workflows.

Create a project and return a signed upload URL for the original media.

POST/v1/create_projectPermissions: write

Endpoint

HTTP request

https://api.diffio.ai/v1/create_project

Use POST with a JSON body.

Permissions

write

API keys must be active.

Authentication

Send the API key on every request using one of the supported headers.

Authorization: Bearer <apiKey>
X-Api-Key: <apiKey>
Xi-Api-Key: <apiKey>

Request

Send metadata for the file you plan to upload.

Body fields

Field	Type	Required	Description
`fileName`	string	Yes	Original file name for the upload.
`contentType`	string	No	MIME type for the upload. Defaults to application/octet-stream.
`contentLength`	number	No	File size in bytes, must be zero or higher.
`fileFormat`	string	No	Short format label. When params.fileFormat is missing, this value is copied into it.
`params`	object	No	Optional parameters stored with the project.
`params.fileFormat`	string	No	Preferred format for downstream processing.

cURL

curl -X POST "https://api.diffio.ai/v1/create_project" \  -H "Authorization: Bearer $DIFFIO_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "fileName": "song.wav",    "contentType": "audio/wav",    "contentLength": 1234567,    "fileFormat": "wav",    "params": {      "fileFormat": "wav"    }  }'

Response

Returns the project id and a signed upload URL.

Response fields

Field	Type	Required	Description
`apiProjectId`	string	Yes	Project identifier for subsequent requests.
`uploadUrl`	string	Yes	Signed URL for uploading the original media.
`uploadMethod`	string	Yes	HTTP method to use when uploading the file.
`objectPath`	string	Yes	Storage path for the uploaded file.
`bucket`	string	Yes	Storage bucket that holds the upload.
`expiresAt`	string	Yes	Upload URL expiration timestamp in ISO 8601 format.

Successful response

{  "apiProjectId": "proj-123",  "uploadUrl": "https://storage.googleapis.com/...",  "uploadMethod": "PUT",  "objectPath": "users/user-123/projects/proj-123/original/song.wav",  "bucket": "diffio_api",  "expiresAt": "2025-01-05T12:35:10Z"}

Return codes

200Success, treated as complete.: Project created, upload URL returned.
204Success, treated as empty response.: CORS preflight when method is OPTIONS.
400Bad request, treated as client error.: Invalid JSON body, fileName must be provided as a string, contentType must be a string, contentLength must be a number, contentLength must be zero or higher, params must be an object.
401Unauthorized, treated as auth error.: Missing API key, or invalid API key.
403Forbidden, treated as permission error.: API key is not active, or missing write permission.
405Client error, treated as fix required.: Method is not POST.
500Server error, treated as retryable.: API key missing userId, failed to create upload record, or failed to generate upload URL.

Notes

fileName is required.
contentLength is coerced to an integer, send whole bytes to avoid truncation.
params can be null, it is treated as an empty object.
fileFormat is expected to be a string, when provided and params.fileFormat is missing it is copied as is.
objectPath uses a sanitized basename of fileName, characters outside letters, digits, period, underscore, and hyphen are replaced with underscores, empty names fall back to upload.bin.
Upload the file to uploadUrl using uploadMethod and set Content-Type to match contentType.
uploadUrl expires at expiresAt, request a new URL if it expires.