Yoto Sample Apps

https://github.com/yotoplay/examples
Admin
This repository contains various example applications demonstrating how to use the Yoto API, with...
Tokens:5,819
Snippets:26
Trust Score:6.5
Update:1 year ago
Show doc for...
Tokens:
Raw
### Start Development Server

Source: https://github.com/yotoplay/examples/blob/main/vanilla-js-html/readme.md

Starts the development server for the project using npm. This command typically builds the project and launches a local server, allowing developers to view and test the application in their browser during development.

```bash
npm start
```

--------------------------------

### Install Dependencies

Source: https://github.com/yotoplay/examples/blob/main/vanilla-js-html/readme.md

Installs the necessary project dependencies using npm. This command downloads and sets up all the required packages listed in the project's package.json file, enabling the application to run.

```bash
npm install
```

--------------------------------

### Copy Environment File

Source: https://github.com/yotoplay/examples/blob/main/vanilla-js-html/readme.md

Copies the example environment file to a new file named '.env' and instructs the user to edit it with their Yoto API credentials. This step is crucial for configuring the application with the correct client ID for authentication.

```bash
cp .env.example .env
```

--------------------------------

### Create .env file for Yoto API Credentials

Source: https://github.com/yotoplay/examples/blob/main/node.js/README.md

Creates a .env file to store sensitive Yoto API credentials, specifically the client ID. This is a common practice for managing environment-specific configurations and keeping secrets out of the codebase.

```bash
echo "YOTO_CLIENT_ID=your_client_id_here" > .env
```

--------------------------------

### Authentication Header Example

Source: https://github.com/yotoplay/examples/blob/main/yoto-labs/DOCS.md

Specifies the required header format for authenticating API requests. All interactions with the Yoto Labs API must include a valid JWT token provided in the 'Authorization' header, prefixed with 'Bearer '.

```HTTP
Authorization: Bearer <your-jwt-token>
```

--------------------------------

### Get Job Status (GET)

Source: https://github.com/yotoplay/examples/blob/main/yoto-labs/DOCS.md

Retrieves the current status of an asynchronous processing job using its unique job ID. The response includes the job's status (queued, processing, completed, failed), progress, and timestamps. For completed jobs, it includes a result object; for failed jobs, it includes an error message.

```JSON
{
  "job": {
    "jobId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "processing",
    "progress": "1/2 (50%)",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:32:15Z"
  }
}
```

```JSON
{
  "job": {
    "jobId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "completed",
    "progress": "2/2 (100%)",
    "result": {
      "cardId": "generated-card-123",
      "title": "My Audio Content"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:35:42Z"
  }
}
```

```JSON
{
  "job": {
    "jobId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "failed",
    "progress": "1/2 (50%)",
    "error": "Failed to process 1 tracks: ElevenLabs API rate limit exceeded",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:35:42Z"
  }
}
```

--------------------------------

### GET /content/job/{jobId}

Source: https://github.com/yotoplay/examples/blob/main/yoto-labs/DOCS.md

Retrieves the current status and details of an asynchronous processing job using its unique job ID. Supports fetching job status, progress, and results upon completion.

```APIDOC
## GET /content/job/{jobId}

### Description
Retrieves the current status and details of an asynchronous processing job using its unique job ID. This endpoint allows clients to poll for job completion and retrieve results.

### Method
GET

### Endpoint
`https://labs.api.yotoplay.com/content/job/{jobId}`

### Parameters
#### Path Parameters
- **jobId** (string) - Required - The unique identifier of the job to retrieve status for.

### Response
#### Success Response (200)
- **job** (object) - Information about the job.
  - **jobId** (string) - The unique identifier for the job.
  - **status** (string) - The current status of the job. Possible values: `queued`, `processing`, `completed`, `failed`.
  - **progress** (string or object) - The progress of the job. Can be a string like "1/2 (50%)" or an object with `total`, `completed`, `failed` fields.
  - **createdAt** (string) - The timestamp when the job was created.
  - **updatedAt** (string) - The timestamp when the job was last updated.
  - **result** (object) - Present only if `status` is `completed`. Contains the outcome of the job.
    - **cardId** (string) - The ID of the generated or updated card.
    - **title** (string) - The title of the content.
  - **error** (string) - Present only if `status` is `failed`. Contains details about the error.

#### Response Example (Processing)
```json
{
  "job": {
    "jobId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "processing",
    "progress": "1/2 (50%)",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:32:15Z"
  }
}
```

#### Response Example (Completed)
```json
{
  "job": {
    "jobId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "completed",
    "progress": "2/2 (100%)",
    "result": {
      "cardId": "generated-card-123",
      "title": "My Audio Content"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:35:42Z"
  }
}
```

#### Response Example (Failed)
```json
{
  "job": {
    "jobId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "failed",
    "progress": "1/2 (50%)",
    "error": "Failed to process 1 tracks: ElevenLabs API rate limit exceeded",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:35:42Z"
  }
}
```

### Job Statuses
- `queued`: Job is waiting to be processed
- `processing`: Job is currently being processed
- `completed`: Job completed successfully
- `failed`: Job failed with errors
```

--------------------------------

### GET /content/job/{jobId}

Source: https://github.com/yotoplay/examples/blob/main/yoto-labs/DOCS.md

Retrieves the status of a specific content job using its job ID. This is used for polling to check the progress of content processing.

```APIDOC
## GET /content/job/{jobId}

### Description
Retrieves the status of a specific content job using its job ID. This is used for polling to check the progress of content processing.

### Method
GET

### Endpoint
https://labs.api.yotoplay.com/content/job/{jobId}

### Parameters
#### Path Parameters
- **jobId** (string) - Required - The unique identifier of the job to check.

### Response
#### Success Response (200)
- **job** (object) - Information about the job status.
  - **jobId** (string) - The unique identifier for the job.
  - **status** (string) - The current status of the job (e.g., "processing", "completed", "failed").

#### Response Example
```json
{
  "job": {
    "jobId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "processing"
  }
}
```
```

--------------------------------

### Check YotoPlay Content Job Status

Source: https://github.com/yotoplay/examples/blob/main/yoto-labs/DOCS.md

This example shows how to retrieve the status of an ongoing content job from the YotoPlay Content API. You need to provide the job ID obtained from the job creation request and your JWT token. The response includes the current status of the job, such as 'queued', 'processing', 'completed', or 'failed'.

```curl
curl -X GET https://labs.api.yotoplay.com/content/job/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer <your-jwt-token>"
```

--------------------------------

### Create Audio Content Job with YotoPlay API

Source: https://github.com/yotoplay/examples/blob/main/yoto-labs/DOCS.md

This snippet demonstrates how to create a new audio content job using the YotoPlay Content API. It requires a JWT token for authorization and a JSON payload specifying content details like chapters, tracks, and metadata. The API returns a job ID upon successful submission.

```curl
curl -X POST https://labs.api.yotoplay.com/content/job \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Audio Content",
    "content": {
      "chapters": [
        {
          "key": "chapter1",
          "title": "Chapter 1",
          "tracks": [
            {
              "key": "track1",
              "title": "The Friendly Dragon",
              "trackUrl": "Once upon a time, in a magical forest, there lived a friendly dragon who loved to read books.",
              "type": "elevenlabs"
            }
          ]
        }
      ]
    },
    "metadata": {
      "title": "My Story",
      "description": "A story about a friendly dragon",
      ...
    }
  }'
```

--------------------------------

### POST /content/job

Source: https://github.com/yotoplay/examples/blob/main/yoto-labs/DOCS.md

Creates a new content job for processing. This endpoint accepts a JSON payload defining the content structure, including chapters, tracks, and metadata.

```APIDOC
## POST /content/job

### Description
Creates a new content job for processing. This endpoint accepts a JSON payload defining the content structure, including chapters, tracks, and metadata.

### Method
POST

### Endpoint
https://labs.api.yotoplay.com/content/job

### Parameters
#### Request Body
- **title** (string) - Required - The title of the audio content.
- **content** (object) - Required - The content structure.
  - **chapters** (array) - Required - An array of chapter objects.
    - **key** (string) - Required - Unique identifier for the chapter.
    - **title** (string) - Required - The title of the chapter.
    - **tracks** (array) - Required - An array of track objects.
      - **key** (string) - Required - Unique identifier for the track.
      - **title** (string) - Required - The title of the track.
      - **trackUrl** (string) - Required - The URL or text content for the audio track.
      - **type** (string) - Required - The type of track, e.g., "elevenlabs".
- **metadata** (object) - Required - Metadata associated with the content.
  - **title** (string) - Required - The title for the metadata.
  - **description** (string) - Required - The description for the metadata.

### Request Example
```json
{
  "title": "My Audio Content",
  "content": {
    "chapters": [
      {
        "key": "chapter1",
        "title": "Chapter 1",
        "tracks": [
          {
            "key": "track1",
            "title": "The Friendly Dragon",
            "trackUrl": "Once upon a time, in a magical forest, there lived a friendly dragon who loved to read books.",
            "type": "elevenlabs"
          }
        ]
      }
    ]
  },
  "metadata": {
    "title": "My Story",
    "description": "A story about a friendly dragon"
  }
}
```

### Response
#### Success Response (200)
- **job** (object) - Information about the created job.
  - **jobId** (string) - The unique identifier for the job.
  - **status** (string) - The initial status of the job (e.g., "queued").

#### Response Example
```json
{
  "job": {
    "jobId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "queued"
  }
}
```
```

--------------------------------

### Create Content Processing Job (POST)

Source: https://github.com/yotoplay/examples/blob/main/yoto-labs/DOCS.md

Submits a new asynchronous processing job for content, including ElevenLabs tracks. Requires an Authorization header with a JWT token. The request body defines the content structure and optional metadata. Returns a job ID and initial status.

```JSON
{
  "title": "My Audio Content",
  "content": {
    "chapters": [
      {
        "key": "chapter1",
        "title": "Chapter 1",
        "tracks": [
          {
            "key": "track1",
            "title": "The Friendly Dragon",
            "trackUrl": "Once upon a time, in a magical forest, there lived a friendly dragon who loved to read books.",
            "type": "elevenlabs",
            "voiceId":"JBFqnCBsd6RMkjVDRZzb" 
          },
          {
            "key": "track2",
            "title": "The Adventure Begins",
            "trackUrl": "The dragon decided to go on an adventure to find the most interesting book in the world.",
            "type": "elevenlabs",
            "voiceId":"JBFqnCBsd6RMkjVDRZzb"
          }
        ]
      }
    ]
  },
  "metadata": {
    "title": "My Story",
    "description": "A story about a friendly dragon",
    ...
  }
}
```

--------------------------------

### POST /content/job

Source: https://github.com/yotoplay/examples/blob/main/yoto-labs/DOCS.md

Creates a new asynchronous processing job for content with ElevenLabs tracks. It allows setting a default voice ID for all tracks via query parameters.

```APIDOC
## POST /content/job

### Description
Creates a new asynchronous processing job for content with ElevenLabs tracks. A `voiceId` query parameter can be used to set a default voice for all text.

### Method
POST

### Endpoint
`https://labs.api.yotoplay.com/content/job`

### Parameters
#### Query Parameters
- **voiceId** (string) - Optional - Sets a default voice ID for all text (e.g., ElevenLabs voice ID).

#### Request Body
- **title** (string) - Required - The title of the audio content.
- **content** (object) - Required - Contains the structure of the content, including chapters and tracks.
  - **chapters** (array) - Required - A list of chapters.
    - **key** (string) - Required - Unique identifier for the chapter.
    - **title** (string) - Required - The title of the chapter.
    - **tracks** (array) - Required - A list of audio tracks within the chapter.
      - **key** (string) - Required - Unique identifier for the track.
      - **title** (string) - Required - The title of the track.
      - **trackUrl** (string) - Required - The source of the audio content (text or URL).
      - **type** (string) - Required - The type of track, e.g., "elevenlabs".
      - **voiceId** (string) - Optional - Overrides the default voice ID for this specific track.
- **metadata** (object) - Optional - Additional metadata for the content.
  - **title** (string) - Optional - The title of the content.
  - **description** (string) - Optional - A description of the content.

### Request Example
```json
{
  "title": "My Audio Content",
  "content": {
    "chapters": [
      {
        "key": "chapter1",
        "title": "Chapter 1",
        "tracks": [
          {
            "key": "track1",
            "title": "The Friendly Dragon",
            "trackUrl": "Once upon a time, in a magical forest, there lived a friendly dragon who loved to read books.",
            "type": "elevenlabs",
            "voiceId":"JBFqnCBsd6RMkjVDRZzb"
          },
          {
            "key": "track2",
            "title": "The Adventure Begins",
            "trackUrl": "The dragon decided to go on an adventure to find the most interesting book in the world.",
            "type": "elevenlabs",
            "voiceId":"JBFqnCBsd6RMkjVDRZzb"
          }
        ]
      }
    ]
  },
  "metadata": {
    "title": "My Story",
    "description": "A story about a friendly dragon"
  }
}
```

### Response
#### Success Response (200)
- **job** (object) - Information about the created job.
  - **jobId** (string) - The unique identifier for the job.
  - **status** (string) - The initial status of the job (e.g., "queued").
  - **progress** (object) - Tracks the progress of the job.
    - **total** (integer) - The total number of tasks to complete.
    - **completed** (integer) - The number of completed tasks.
    - **failed** (integer) - The number of failed tasks.
  - **createdAt** (string) - The timestamp when the job was created.

#### Response Example
```json
{
  "job": {
    "jobId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "queued",
    "progress": {
      "total": 2,
      "completed": 0,
      "failed": 0
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}
```
```

--------------------------------

### POST /content/{cardId}/job

Source: https://github.com/yotoplay/examples/blob/main/yoto-labs/DOCS.md

Creates a new asynchronous processing job to update an existing card with ElevenLabs tracks. This endpoint allows modification of existing content.

```APIDOC
## POST /content/{cardId}/job

### Description
Creates a new asynchronous processing job to update an existing card with ElevenLabs tracks. This endpoint is used for modifying existing content.

### Method
POST

### Endpoint
`https://labs.api.yotoplay.com/content/{cardId}/job`

### Parameters
#### Path Parameters
- **cardId** (string) - Required - The ID of the card to update.

#### Request Body
- **content** (object) - Required - Contains the structure of the content to update, including chapters and tracks.
  - **chapters** (array) - Required - A list of chapters.
    - **key** (string) - Required - Unique identifier for the chapter.
    - **title** (string) - Required - The title of the chapter.
    - **tracks** (array) - Required - A list of audio tracks within the chapter.
      - **key** (string) - Required - Unique identifier for the track.
      - **title** (string) - Required - The title of the track.
      - **trackUrl** (string) - Required - The source of the audio content (text or URL).
      - **type** (string) - Required - The type of track, e.g., "elevenlabs".
- **metadata** (object) - Optional - Additional metadata for the content.
  - **title** (string) - Optional - The title of the content.
  - **description** (string) - Optional - A description of the content.

### Request Example
```json
{
  "content": {
    "chapters": [
      {
        "key": "chapter1",
        "title": "Chapter 1",
        "tracks": [
          {
            "key": "track1",
            "title": "The Friendly Dragon",
            "trackUrl": "Once upon a time, in a magical forest, there lived a friendly dragon who loved to read books.",
            "type": "elevenlabs"
          }
        ]
      }
    ]
  },
  "metadata": {
    "title": "My Story",
    "description": "A story about a friendly dragon"
  }
}
```

### Response
#### Success Response (200)
- **job** (object) - Information about the created job.
  - **jobId** (string) - The unique identifier for the job.
  - **status** (string) - The initial status of the job (e.g., "queued").
  - **progress** (object) - Tracks the progress of the job.
    - **total** (integer) - The total number of tasks to complete.
    - **completed** (integer) - The number of completed tasks.
    - **failed** (integer) - The number of failed tasks.
  - **createdAt** (string) - The timestamp when the job was created.

#### Response Example
```json
{
  "job": {
    "jobId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "queued",
    "progress": {
      "total": 1,
      "completed": 0,
      "failed": 0
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}
```
```

--------------------------------

### POST /content/existing-card-{cardId}/job

Source: https://github.com/yotoplay/examples/blob/main/yoto-labs/DOCS.md

Updates an existing content card by creating a new job. This endpoint allows for modifications to the content and metadata of a previously created card.

```APIDOC
## POST /content/existing-card-{cardId}/job

### Description
Updates an existing content card by creating a new job. This endpoint allows for modifications to the content and metadata of a previously created card.

### Method
POST

### Endpoint
https://labs.api.yotoplay.com/content/existing-card-{cardId}/job

### Parameters
#### Path Parameters
- **cardId** (string) - Required - The unique identifier of the existing card to update.

#### Request Body
- **content** (object) - Required - The updated content structure.
  - **chapters** (array) - Required - An array of chapter objects.
    - **key** (string) - Required - Unique identifier for the chapter.
    - **title** (string) - Required - The title of the chapter.
    - **tracks** (array) - Required - An array of track objects.
      - **key** (string) - Required - Unique identifier for the track.
      - **title** (string) - Required - The title of the track.
      - **trackUrl** (string) - Required - The URL or text content for the audio track.
      - **type** (string) - Required - The type of track, e.g., "elevenlabs".
- **metadata** (object) - Required - The updated metadata associated with the content.
  - **title** (string) - Required - The title for the metadata.
  - **description** (string) - Required - The description for the metadata.

### Request Example
```json
{
  "content": {
    "chapters": [
      {
        "key": "chapter1",
        "title": "Updated Chapter",
        "tracks": [
          {
            "key": "track1",
            "title": "New Audio Track",
            "trackUrl": "This is new content for the existing card.",
            "type": "elevenlabs"
          }
        ]
      }
    ]
  },
  "metadata": {
    "title": "Content Title",
    "description": "Updated content"
  }
}
```

### Response
#### Success Response (200)
- **job** (object) - Information about the created job for updating the card.
  - **jobId** (string) - The unique identifier for the job.
  - **status** (string) - The initial status of the job (e.g., "queued").

#### Response Example
```json
{
  "job": {
    "jobId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "status": "queued"
  }
}
```
```

--------------------------------

### Update Existing Card Content with YotoPlay API

Source: https://github.com/yotoplay/examples/blob/main/yoto-labs/DOCS.md

This snippet illustrates how to update the content of an existing card using the YotoPlay Content API. It uses a POST request to a specific card endpoint, providing the card ID and a JSON payload with updated content details. This is useful for revising or adding new audio tracks and metadata to previously published content.

```curl
curl -X POST https://labs.api.yotoplay.com/content/existing-card-123/job \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "chapters": [
        {
          "key": "chapter1",
          "title": "Updated Chapter",
          "tracks": [
            {
              "key": "track1",
              "title": "New Audio Track",
              "trackUrl": "This is new content for the existing card.",
              "type": "elevenlabs"
            }
          ]
        }
      ]
    },
    "metadata": {
      "title": "Content Title"
      "description": "Updated content",
      ...
    }
  }'
```

--------------------------------

### Update Existing Card Job (POST)

Source: https://github.com/yotoplay/examples/blob/main/yoto-labs/DOCS.md

Creates a new asynchronous processing job to update an existing card with new content, including ElevenLabs tracks. Requires an Authorization header with a JWT token. The request body specifies the content to be updated and optional metadata. Returns a job ID and initial status.

```JSON
{
  "content": {
    "chapters": [
      {
        "key": "chapter1",
        "title": "Chapter 1",
        "tracks": [
          {
            "key": "track1",
            "title": "The Friendly Dragon",
            "trackUrl": "Once upon a time, in a magical forest, there lived a friendly dragon who loved to read books.",
            "type": "elevenlabs"
          }
        ]
      }
    ]
  },
  "metadata": {
    "title": "My Story",
    "description": "A story about a friendly dragon",
    ...
  }
}
```

--------------------------------

### Authentication

Source: https://github.com/yotoplay/examples/blob/main/yoto-labs/DOCS.md

All API requests must include a valid JWT token in the Authorization header for authentication.

```APIDOC
## Authentication

All API requests require a valid JWT token in the Authorization header:

```
Authorization: Bearer <your-jwt-token>
```
```
Tokens:
Raw