mirror of
https://github.com/hzrd149/blossom.git
synced 2025-12-09 07:08:50 +00:00
88 lines
3.2 KiB
Markdown
88 lines
3.2 KiB
Markdown
BUD-05
|
|
======
|
|
|
|
Media optimization endpoints
|
|
|
|
`draft` `optional`
|
|
|
|
Defines the `PUT /media`, `GET /media/<task>` and `DELETE /media/<task>` endpoints for processing and optimizing media
|
|
|
|
## Task Object
|
|
|
|
The task object defines a long running media processing task on the server. A task MUST have the following fields
|
|
|
|
- `id` A unique id for the task **(required)**
|
|
- `status` The status of the job, either `running`, `complete`, or `canceled` **(required)**
|
|
- `message` A human-readable description of what is happening or the current status *(optional)*
|
|
- `progress` A number from 0 to 100 representing the percentage of the task that is complete *(optional)*
|
|
- `blob` A full [Blob Descriptor](./02.md#blob-descriptor) **(required when `complete`)**
|
|
|
|
## PUT /media
|
|
|
|
The `PUT /media` endpoint MUST accept binary data in the body of the request and MAY use the `Content-Type` and `Content-Length` headers to get the MIME type and size of the media
|
|
|
|
The server should preform any optimizations or conversions it deems necessary in order to make the media more suitable for distribution
|
|
|
|
The endpoint MUST return a status code of `202` with `Content-Type: application/json` and a [task object](#task-object) or an [error response](./01.md#error-responses)
|
|
|
|
Servers MAY reject a media upload for any reason and should respond with the appropriate HTTP `4xx` status code and an error message explaining the reason for the rejection
|
|
|
|
### Upload Authorization
|
|
|
|
Servers may require an `upload` [authorization event](./02.md#upload-authorization-required) to identify the uploader
|
|
|
|
If a server requires an `upload` authorization event it MUST preform all the [checks](./02.md#upload-authorization-required) that the `/upload` endpoint does, including that the `x` tag value matches the sha256 hash of the uploaded blob
|
|
|
|
## GET /media/task
|
|
|
|
Servers may expose a `GET /media/<task id>` endpoint to allow clients to get the results or check on the progress of a task
|
|
|
|
The endpoint MUST return a `2xx` status code and a [task object](#task-object) if a task with `<task id>` exists or an [error response](./01.md#error-responses)
|
|
|
|
The `blob` field MUST be set to a [Blob Descriptor](./02.md#blob-descriptor) when the task `status` is `complete`
|
|
|
|
Servers may delete (or forget) tasks after a self determined amount of time after the task status is `complete`
|
|
|
|
## DELETE /media/task
|
|
|
|
Servers may expose a `DELETE /media/<task id>` endpoint to allow clients to cancel a processing request
|
|
|
|
## Examples
|
|
|
|
Upload image `PUT /media`
|
|
```json
|
|
{
|
|
"id": "0e81bf11-eb84-49b8-a7f0-4c7c60254f2e",
|
|
"status": "running",
|
|
"progress": 0,
|
|
"message": "Resizing Image"
|
|
}
|
|
```
|
|
|
|
Example `GET /media/eb6e7ec1-b752-4740-91bb-9aaddf92bc57`:
|
|
```json
|
|
{
|
|
"id": "eb6e7ec1-b752-4740-91bb-9aaddf92bc57",
|
|
"status": "running",
|
|
"progress": 24,
|
|
"message": "Resizing Video"
|
|
}
|
|
```
|
|
|
|
Example `GET /media/eb6e7ec1-b752-4740-91bb-9aaddf92bc57`:
|
|
```json
|
|
{
|
|
"id": "eb6e7ec1-b752-4740-91bb-9aaddf92bc57",
|
|
"status": "complete",
|
|
"progress": 100,
|
|
"message": "Finished optimizing video",
|
|
"blob": {
|
|
"url": "https://cdn.example.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.webm",
|
|
"sha256": "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553",
|
|
"size": 18431531,
|
|
"type": "video/webm",
|
|
"uploaded": 1722386093
|
|
}
|
|
}
|
|
```
|