# API and Usage

Base URL:
- `https://video.renderingvideo.com`

Public flow:
- Use `POST /api/preview` to create a preview
- Use `/t/:id` or `/preview/:id` as the playback link
- Preview links expire in 7 days
- Do not rely on undocumented internal routes

## 1. Temporary link API

External endpoints:
- `POST /api/preview`
- `GET /api/temp/:id`
- `GET /t/:id`
- `GET /preview/:id`
- `GET /`

Temporary link behavior:
- Preview data is stored in KV
- Default expiration is 7 days
- The returned preview page can be shared directly with external users

## 2. `POST /api/preview`

Purpose:
- Submit one schema for preview
- Run top-level structure validation
- Generate a temporary preview link

### Request headers

```http
Content-Type: application/json
```

### Request body

Send the full schema JSON directly as the request body.

Minimal example:

```json
{
  "meta": {
    "version": "2.0.0",
    "width": 1920,
    "height": 1080,
    "fps": 30
  },
  "tracks": [
    {
      "clips": [
        {
          "type": "text",
          "start": 0,
          "duration": 3,
          "text": "Temporary Preview"
        }
      ]
    }
  ]
}
```

### Success response

```json
{
  "success": true,
  "tempId": "uuid",
  "url": "/t/uuid",
  "viewerUrl": "/preview/uuid",
  "expiresIn": "604800 seconds (7 days)"
}
```

Response fields:
- `url`: clean player page
- `viewerUrl`: preview page variant
- `tempId`: the identifier used to read the temp config later

### Common failure cases

The request can fail because of:
- Invalid JSON
- Missing top-level `meta` or `tracks`
- A body not matching the current `VideoSchema`

## 3. `GET /api/temp/:id`

Purpose:
- Read the schema behind a temporary link
- Let your application inspect the current preview config

### Success response

```json
{
  "success": true,
  "config": {
    "meta": {
      "version": "2.0.0",
      "width": 1920,
      "height": 1080,
      "fps": 30
    },
    "tracks": [
      {
        "clips": [
          {
            "type": "text",
            "start": 0,
            "duration": 3,
            "text": "Temporary Preview"
          }
        ]
      }
    ]
  }
}
```

Common failure cases:
- `id` is not a valid UUID
- The temp link does not exist
- The temp link has expired

## 4. Preview pages

Temporary links expose two playback pages:
- `GET /t/:id`: clean player page
- `GET /preview/:id`: preview page variant

If the temp link is expired, those pages return an invalid-state message.

- The public API guarantees the preview URLs, not internal player implementation details
- Do not depend on undocumented asset proxy paths, client-side rewrite logic, or internal runtime helpers

## 5. Recommended external flow

Recommended order:
1. Build `meta / assets / tracks`
2. Put reusable media in `assets` whenever possible
3. Reference media through `$ref` inside clips when appropriate
4. Submit to `POST /api/preview`
5. Share the returned `/t/:id` or `/preview/:id`
6. If needed later, convert the temp preview into a permanent task through your application flow

## 6. Authoring recommendations

### Recommendation 1

Prefer `$ref` for reusable media instead of repeating URLs in multiple clips.

### Recommendation 2

If subtitles come from an external service, a stable response shape is:

```json
{
  "words": [
    {
      "word": "hello",
      "punctuated_word": "Hello",
      "start": 0,
      "end": 0.4
    }
  ]
}
```

### Recommendation 3

Do not rely on undocumented fields or internal implementation details that are not part of the public API.

## 7. Debugging checklist

If the output does not match expectations, check these first:
- Are you still sending a legacy top-level `video` object
- Does your schema include valid `meta.version`, `meta.width`, `meta.height`, and `tracks`
- Are remote media URLs directly accessible by the playback environment
- Has the temporary link already expired

## 8. Example request

```bash
curl -X POST https://video.renderingvideo.com/api/preview \
  -H "Content-Type: application/json" \
  -d @temp-preview.json
```

More examples: [Examples](https://renderingvideo.com/docs/examples.md)