Timeline API Documentation

Welcome to the Timeline API documentation. This API allows you to manage timelines, including creating, updating, deleting, and retrieving timeline information. The API uses X-API-Key for authentication.

Table of Contents

• Authentication
• Base URL
• Endpoints
  • Get Timelines
  • Create Timeline
  • Get Timeline
  • Update Timeline
  • Delete Timeline
  • Generate Timeline by Subject
  • Generate Timeline Highlight
  • Refine Timeline
  • Export Timeline
• Notes
• Common Status Codes
• Contact
• Examples of Usage
  • Handling Errors
• Conclusion

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

Endpoints

Get Timelines

Retrieve a list of all timelines for the authenticated user.

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

Response

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

Example

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

Create Timeline

Create a new timeline.

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

Request Body Parameters

Response

• Status Code: 200 OK
• Body: The created timeline object.

Example

import requests
 
url = "https://api.play-video.dev/timelines"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY"
}
data = {
    "name": "My Timeline",
    "preview_image": "https://example.com/image.png",
    "timeline_data": {...},
    "source_prompt": "Create a timeline about...",
    "tags": ["tag1", "tag2"]
}
 
response = requests.post(url, headers=headers, json=data)
print(response.json())

Get Timeline

Retrieve a specific timeline by UUID.

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

Response

• Status Code: 200 OK
• Body: The timeline object.

Example

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

Update Timeline

Update an existing timeline.

• URL: /timelines/{uuid}
• Method: PUT
• Headers:
  • Content-Type: application/json
  • X-API-Key: YOUR_API_KEY
• Path Parameters:
  • uuid: The UUID of the timeline to update.

Request Body Parameters

Response

• Status Code: 200 OK
• Body: The updated timeline object.

Example

import requests
 
timeline_uuid = "TIMELINE_UUID"
url = f"https://api.play-video.dev/timelines/{timeline_uuid}"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY"
}
data = {
    "name": "Updated Timeline Name",
    "timeline_data": {...}
}
 
response = requests.put(url, headers=headers, json=data)
print(response.json())

Delete Timeline

Delete a timeline.

• URL: /timelines/{uuid}
• Method: DELETE
• Headers:
  • X-API-Key: YOUR_API_KEY
• Path Parameters:
  • uuid: The UUID of the timeline to delete.

Response

• Status Code: 200 OK
• Body:

{
  "message": "Timeline deleted successfully"
}

Example

import requests
 
timeline_uuid = "TIMELINE_UUID"
url = f"https://api.play-video.dev/timelines/{timeline_uuid}"
headers = {
    "X-API-Key": "YOUR_API_KEY"
}
 
response = requests.delete(url, headers=headers)
print(response.json())

Generate Timeline by Subject

Generate a timeline based on specific subjects.

• URL: /timelines/generate/subject
• Method: POST
• Headers:
  • Content-Type: application/json
  • X-API-Key: YOUR_API_KEY

Request Body Parameters

Response

• Status Code: 200 OK
• Body: The generated timeline object.

Example

import requests
 
url = "https://api.play-video.dev/timelines/generate/subject"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "Create a timeline about environmental conservation",
    "files": ["FILE_UUID1", "FILE_UUID2"],
    "subjects": ["PERSON_UUID1", "PLACE_UUID1"]
}
 
response = requests.post(url, headers=headers, json=data)
print(response.json())

Generate Timeline Highlight

Generate a timeline highlight based on specific subjects.

• URL: /timelines/generate/highlight
• Method: POST
• Headers:
  • Content-Type: application/json
  • X-API-Key: YOUR_API_KEY

Request Body Parameters

Response

• Status Code: 200 OK
• Body: The generated timeline highlight object.

Example

import requests
 
url = "https://api.play-video.dev/timelines/generate/highlight"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "Highlight key moments about climate change",
    "files": ["FILE_UUID1", "FILE_UUID2"],
    "subjects": ["PERSON_UUID1", "PERSON_UUID2"]
}
 
response = requests.post(url, headers=headers, json=data)
print(response.json())

Refine Timeline

Refine an existing timeline based on a new prompt.

• URL: /timelines/{uuid}/refine
• Method: POST
• Headers:
  • Content-Type: application/json
  • X-API-Key: YOUR_API_KEY
• Path Parameters:
  • uuid: The UUID of the timeline to refine.

Request Body Parameters

Response

• Status Code: 200 OK
• Body: The refined timeline object.

Example

import requests
 
timeline_uuid = "TIMELINE_UUID"
url = f"https://api.play-video.dev/timelines/{timeline_uuid}/refine"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "Refine the timeline to focus on renewable energy",
    "subjects": ["PERSON_UUID1", "PERSON_UUID2"]
}
 
response = requests.post(url, headers=headers, json=data)
print(response.json())

Export Timeline

Export a timeline in a specific format.

• URL: /timelines/{uuid}/export/{format}
• Method: POST
• Headers:
  • X-API-Key: YOUR_API_KEY
• Path Parameters:
  • uuid: The UUID of the timeline to export.
  • format: The format to export the timeline in.

Supported Formats

• otio
• fcp_xml
• json
• cmx_3600

Response

• Status Code: 200 OK
• Body: The exported timeline in the requested format.

Example

import requests
 
timeline_uuid = "TIMELINE_UUID"
format = "otio"
url = f"https://api.play-video.dev/timelines/{timeline_uuid}/export/{format}"
headers = {
    "X-API-Key": "YOUR_API_KEY"
}
 
response = requests.post(url, headers=headers)
# Handle response based on format
if format == "json":
    print(response.json())
else:
    with open(f"timeline.{format}", "wb") as f:
        f.write(response.content)

Notes

• Replace YOUR_API_KEY with your actual API key.
• Replace TIMELINE_UUID with the UUID of the timeline you are interacting with.
• Replace FILE_UUID1, FILE_UUID2, etc., with the UUIDs of your files.
• The timeline_data field in the request body should be a valid JSON object representing the timeline structure.
• 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.

Contact

If you have any questions or need assistance, please contact our support team at support@play-video.dev.

Examples of Usage

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

Handling Errors

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

Example

import requests
 
timeline_uuid = "INVALID_UUID"
url = f"https://api.play-video.dev/timelines/{timeline_uuid}"
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: Timeline not found.")
else:
    print(f"Error {response.status_code}: {response.text}")