API
Assets

Asset Management API Documentation

Welcome to the Asset Management API documentation. This API allows you to manage assets, including creating, deleting, editing, and retrieving asset information. The API uses X-API-Key for authentication.

Table of Contents

Authentication

All API requests require an API key for authentication. Include your API key in the X-API-Key header in each request.

X-API-Key: YOUR_API_KEY

Base URL

https://api.play-video.dev

Replace https://api.play-video.dev with the actual base URL of the API.

Endpoints

Create Asset

Create a new asset.

  • URL: /asset/create
  • Method: POST
  • Headers:
    • Content-Type: application/json
    • X-API-Key: YOUR_API_KEY

Request Body Parameters

NameTypeDescription
filenamestringThe name of the file to be uploaded.
indexer_profile_uuidstringUUID of the indexer profile to be used.

Response

  • Status Code: 200 OK
  • Body:
{
  "uuid": "string",
  "s3_presigned_url": "string"
}
  • uuid: The unique identifier of the created asset.
  • s3_presigned_url: A presigned URL to upload the asset to S3.

Example

import requests
 
url = "https://api.play-video.dev/asset/create"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY"
}
data = {
    "filename": "example.mp4",
    "indexer_profile_uuid": "123e4567-e89b-12d3-a456-426614174000"
}
 
response = requests.post(url, headers=headers, json=data)
print(response.json())

Delete Asset

Delete an existing asset.

  • URL: /asset/{uuid}
  • Method: DELETE
  • Headers:
    • X-API-Key: YOUR_API_KEY
  • Path Parameters:
    • uuid: The UUID of the asset to be deleted.

Response

  • Status Code: 200 OK
  • Body: Empty

Example

import requests
 
asset_uuid = "ASSET_UUID"
url = f"https://api.play-video.dev/asset/{asset_uuid}"
headers = {
    "X-API-Key": "YOUR_API_KEY"
}
 
response = requests.delete(url, headers=headers)
print(response.status_code)

Edit Asset

Edit the metadata of an existing asset.

  • URL: /asset/{uuid}/edit
  • Method: PATCH
  • Headers:
    • Content-Type: application/json
    • X-API-Key: YOUR_API_KEY
  • Path Parameters:
    • uuid: The UUID of the asset to be edited.

Request Body Parameters

NameTypeDescription
tagsarrayA list of tags to associate with the asset (optional).
titlestringA new title for the asset (optional).

Response

  • Status Code: 200 OK
  • Body:
{
  "message": "Asset updated successfully"
}

Example

import requests
 
asset_uuid = "ASSET_UUID"
url = f"https://api.play-video.dev/asset/{asset_uuid}/edit"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY"
}
data = {
    "tags": ["tag1", "tag2"],
    "title": "New Asset Title"
}
 
response = requests.patch(url, headers=headers, json=data)
print(response.json())

Fetch Asset Audio Segments

Retrieve the audio segments of an asset.

  • URL: /asset/{uuid}/audio_segments
  • Method: GET
  • Headers:
    • X-API-Key: YOUR_API_KEY
  • Path Parameters:
    • uuid: The UUID of the asset.

Response

  • Status Code: 200 OK
  • Body:
{
  "audio_segments": [...]
}

Example

import requests
 
asset_uuid = "ASSET_UUID"
url = f"https://api.play-video.dev/asset/{asset_uuid}/audio_segments"
headers = {
    "X-API-Key": "YOUR_API_KEY"
}
 
response = requests.get(url, headers=headers)
print(response.json())

Fetch Asset Metadata

Retrieve metadata of an asset.

  • URL: /asset/{uuid}/metadata
  • Method: GET
  • Headers:
    • X-API-Key: YOUR_API_KEY
  • Path Parameters:
    • uuid: The UUID of the asset.

Response

  • Status Code: 200 OK
  • Body: JSON object containing metadata fields.

Example

import requests
 
asset_uuid = "ASSET_UUID"
url = f"https://api.play-video.dev/asset/{asset_uuid}/metadata"
headers = {
    "X-API-Key": "YOUR_API_KEY"
}
 
response = requests.get(url, headers=headers)
print(response.json())

Fetch Asset Segments

Retrieve the segments of an asset.

  • URL: /asset/{uuid}/segments
  • Method: GET
  • Headers:
    • X-API-Key: YOUR_API_KEY
  • Path Parameters:
    • uuid: The UUID of the asset.

Response

  • Status Code: 200 OK
  • Body:
{
  "segments": [...]
}

Example

import requests
 
asset_uuid = "ASSET_UUID"
url = f"https://api.play-video.dev/asset/{asset_uuid}/segments"
headers = {
    "X-API-Key": "YOUR_API_KEY"
}
 
response = requests.get(url, headers=headers)
print(response.json())

Fetch Assets

Retrieve a list of all ready assets for the authenticated user.

  • URL: /assets/
  • Method: GET
  • Headers:
    • X-API-Key: YOUR_API_KEY

Response

  • Status Code: 200 OK
  • Body: An array of asset objects.

Example

import requests
 
url = "https://api.play-video.dev/assets/"
headers = {
    "X-API-Key": "YOUR_API_KEY"
}
 
response = requests.get(url, headers=headers)
print(response.json())

Fetch Pending Assets

Retrieve a list of all pending assets for the authenticated user.

  • URL: /assets/pending
  • Method: GET
  • Headers:
    • X-API-Key: YOUR_API_KEY

Response

  • Status Code: 200 OK
  • Body: An array of pending asset objects.

Example

import requests
 
url = "https://api.play-video.dev/assets/pending"
headers = {
    "X-API-Key": "YOUR_API_KEY"
}
 
response = requests.get(url, headers=headers)
print(response.json())

Get Asset Status

Retrieve the current status of an asset.

  • URL: /asset/{uuid}/status
  • Method: GET
  • Headers:
    • X-API-Key: YOUR_API_KEY
  • Path Parameters:
    • uuid: The UUID of the asset.

Response

  • Status Code: 200 OK
  • Body:
{
  "uuid": "string",
  "status": "string"
}

Example

import requests
 
asset_uuid = "ASSET_UUID"
url = f"https://api.play-video.dev/asset/{asset_uuid}/status"
headers = {
    "X-API-Key": "YOUR_API_KEY"
}
 
response = requests.get(url, headers=headers)
print(response.json())

Update Asset Status

Update the status of an asset.

  • URL: /asset/{uuid}/status
  • Method: PATCH
  • Headers:
    • Content-Type: application/json
    • X-API-Key: YOUR_API_KEY
  • Path Parameters:
    • uuid: The UUID of the asset.

Request Body Parameters

NameTypeDescription
asset_statusstringThe new status of the asset.

Possible values for asset_status:

  • CREATED
  • INDEXING
  • READY
  • FAILED

Response

  • Status Code: 200 OK
  • Body:
{
  "message": "Asset status updated successfully"
}

Example

import requests
 
asset_uuid = "ASSET_UUID"
url = f"https://api.play-video.dev/asset/{asset_uuid}/status"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY"
}
data = {
    "asset_status": "READY"
}
 
response = requests.patch(url, headers=headers, json=data)
print(response.json())

Notes

  • Replace YOUR_API_KEY with your actual API key.
  • Replace ASSET_UUID with the UUID of the asset you are interacting with.
  • The API responses include various data fields; ensure you handle them according to your application's needs.
  • Error handling is crucial. Be prepared to handle different HTTP status codes and error messages returned by the API.

Common Status Codes

  • 200 OK: The request was successful.
  • 400 Bad Request: The request was malformed or invalid.
  • 401 Unauthorized: Authentication failed or was not provided.
  • 404 Not Found: The requested resource was not found.
  • 500 Internal Server Error: An error occurred on the server.

Examples of Usage

Below are more detailed examples of how to use the API endpoints using both curl and Python's requests library.

Uploading an Asset File

After creating an asset and receiving the s3_presigned_url, you can upload the asset file to S3 using the presigned URL.

Using Curl

curl -X PUT "S3_PRESIGNED_URL" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "@path/to/your/file.mp4"

Replace S3_PRESIGNED_URL with the s3_presigned_url received from the /asset/create endpoint. Replace path/to/your/file.mp4 with the actual path to your file.

Using Python

import requests
 
s3_presigned_url = "S3_PRESIGNED_URL"
file_path = "path/to/your/file.mp4"
 
with open(file_path, 'rb') as f:
    response = requests.put(s3_presigned_url, data=f)
print(response.status_code)

Handling Errors

It's important to handle errors gracefully in your application.

Example

import requests
 
url = "https://api.play-video.dev/asset/invalid-uuid/metadata"
headers = {
    "X-API-Key": "YOUR_API_KEY"
}
 
response = requests.get(url, headers=headers)
 
if response.status_code == 200:
    print("Success:", response.json())
elif response.status_code == 404:
    print("Error: Asset not found.")
else:
    print(f"Error {response.status_code}: {response.text}")
APIIndexing