UPOZORNĚNÍ: API je nová funkce, která je stále ve vývoji

Pokud narazíta na nějaké problémy nebo budete mít návrh na vylepšení ozvete se nám na info@cesky.ai

API Dokumentace

Každý požadavek na API musí obsahovat HTTP hlavičku Access-Token s hodnotou vašeho API tokenu. Pokud uvedete nesprávný či neexistující API token, obdržíte odpověď s chybou 401 Unauthorized

Základní URL: https://cesky.ai/api/v1

Založení nové úlohy

Endpoint: /task
Metoda: POST

Popis:

Tento endpoint slouží k vytvoření nové úlohy. Po úspěšném vytvoření úlohy API vrátí informace o nové úloze včetně jejího UUID, které lze použít pro další operace - upload, získání výstupu atd. Spoučástí odpovědi je i <code>uploadUrl</code> sloužící k následnému nahrání samotného souboru k přepisu.

Tělo požadavku (Body):

  • promptName (string, volitelné) - Název rozhovoru/pořadu/podcastu
  • promptSpeakers (string, volitelné) - Jména řečníků
  • promptKeywords (string, volitelné) - Neobvyklá slova, jména a názvy
  • promptDescription (string, volitelné) - Probíraná témata
  • language (string, volitelné) - Jazyk nahrávky. Dostupné jazyky: cs = Čeština, sk = Slovenština, cs+sk = Čeština a slovenština. Výchozí: cs (Čeština)

Možné odpovědi:

  • 201 Created - Úloha byla úspěšně vytvořena.
  • 400 Bad Request - Chyba validace dat.
  • 401 Unauthorized - Chybějící nebo neznámý API token.
  • 429 Too Many Requests - Přesáhnutý limit úloh čekajích na zpracování (viz. Předplatné).

        {
          "promptName": "Rozhovor s Honzou",
          "promptSpeakers": "Jan Novák, Petr Tomáš",
          "promptKeywords": "zdraví, život, počasí",
          "promptDescription": "Rozhovor s Honzou o jeho životě a cestě za zdravým životním stylem.",
          "numberOfSpeakers": 2
        }

        {
          "status": "success",
          "upload_url": "https://cesky.ai/api/v1/tasks/01922322-a946-72e5-a875-25396aa4ac11/upload",
          "task": {
            "uuid": "01922322-a946-72e5-a875-25396aa4ac11",
            "created": "2024-09-24 10:25:26",
            "creditCost": 0,
            "email": "app@app.cz",
            "fileName": null,
            "fileSize": null,
            "finished": null,
            "isConfirmed": true,
            "isDuplicate": false,
            "isPaused": false,
            "lengthSeconds": null,
            "numberOfSpeakers": 2,
            "promptDescription": "Rozhovor s Honzou o jeho životě a cestě za zdravým životním stylem.",
            "promptKeywords": "zdraví, život, počasí",
            "promptName": "Rozhovor s Honzou",
            "promptSpeakers": "Jan Novák, Petr Tomáš",
            "retention": null,
            "started": null,
            "status": "new-incomplete",
            "title": null
            }
        }

Nahrání souboru k založené úloze

Endpoint: /tasks/[uuid]/upload
Metoda: POST

Popis:

Tento endpoint umožňuje nahrání souboru (např. audio nebo video) k existující úloze identifikované UUID. Soubor je odeslán jako raw body bez dalších metadat.

Parametry URL:

  • uuid (string, povinný) - Identifikátor úlohy, ke které chcete nahrát soubor.

Tělo požadavku (Body):

  • Zvukový nebo video soubor (povinný) - Jako binární obsah. Doporučujeme formáty: .mp3, .m4a, .wma, .wav (lze i .mp4, .mpg, .mpeg, .avi, .wmv, .webm, .m4b, .m4v, .mkv, .ac3, ...)

Možné odpovědi:

  • 201 Created - Soubor úspěšně nahrán k přepisu.
  • 400 Bad Request - Prázdné tělo požadavku nebo jiná chyba.
  • 404 Not Found - Úloha se zadaným UUID nenalezena.
  • 415 Unsupported Media Type - Neočekáváný formát souboru.
  • 401 Unauthorized - Chybějící nebo neznámý API token.
<obsah souboru>

    {
      "status": "success",
      "task": {
      "uuid": "01922322-a946-72e5-a875-25396aa4ac11",
      "created": "2024-09-24 10:25:26",
      "creditCost": 2,
      "email": "app@app.cz",
      "fileName": null,
      "fileSize": 646793,
      "finished": null,
      "isConfirmed": true,
      "isDuplicate": false,
      "isPaused": false,
      "lengthSeconds": 96,
      "numberOfSpeakers": 2,
      "promptDescription": "Rozhovor s Honzou o jeho životě a cestě za zdravým životním stylem.",
      "promptKeywords": "zdraví, život, počasí",
      "promptName": "Rozhovor s Honzou",
      "promptSpeakers": "Jan Novák, Petr Tomáš",
      "retention": null,
      "started": null,
      "status": "new",
      "title": "Rozhovor s Honzou",
    }
    }

Získání informací o úloze

Endpoint: /tasks/[uuid]
Metoda: GET

Popis:

Tento endpoint vrací podrobné informace o úloze včetně odkazů na získání výstupů.

Parametry URL:

  • uuid (string, povinný) - Identifikátor úlohy, o které chcete získat informace.

Možné odpovědi:

  • 200 OK - Informace o úloze byly úspěšně načteny.
  • 403 Forbidden - Úloha patří jinému uživateli.
  • 404 Not Found - Úloha s daným UUID neexistuje.

    {
      "status": "success",
      "task": {
        "uuid": "01922322-a946-72e5-a875-25396aa4ac11",
        "created": "2024-09-24 10:25:26",
        "creditCost": 2,
        "email": "app@app.cz",
        "fileName": null,
        "fileSize": 646793,
        "finished": "2024-09-24 10:58:48",
        "isConfirmed": true,
        "isDuplicate": false,
        "isPaused": false,
        "lengthSeconds": 96,
        "numberOfSpeakers": 2,
        "promptDescription": "Rozhovor s Honzou o jeho životě a cestě za zdravým životním stylem.",
        "promptKeywords": "zdraví, život, počasí",
        "promptName": "Rozhovor s Honzou",
        "promptSpeakers": "Jan Novák, Petr Tomáš",
        "retention": "2025-09-24 10:58:48",
        "started": "2024-09-24 10:56:37",
        "status": "finished",
        "title": "Rozhovor s Honzou",
        "transcribed-txt": "https://cesky.ai/api/v1/task/01922322-a946-72e5-a875-25396aa4ac11/transcribed-txt",
        "transcribed-json": "https://cesky.ai/api/v1/01922322-a946-72e5-a875-25396aa4ac11/e6c7fb7e/transcribed-json",
        "transcribed-srt": "https://cesky.ai/api/v1/01922322-a946-72e5-a875-25396aa4ac11/e6c7fb7e/transcribed-srt",
        "transcribed-vtt": "https://cesky.ai/api/v1/01922322-a946-72e5-a875-25396aa4ac11/e6c7fb7e/transcribed-vtt",
        "result-txt": "https://cesky.ai/api/v1/01922322-a946-72e5-a875-25396aa4ac11/e6c7fb7e/resutl-txt",
        "result-json": "https://cesky.ai/api/v1/01922322-a946-72e5-a875-25396aa4ac11/e6c7fb7e/result-json",
        "result-srt": "https://cesky.ai/api/v1/01922322-a946-72e5-a875-25396aa4ac11/e6c7fb7e/result-srt",
        "result-vtt": "https://cesky.ai/api/v1/01922322-a946-72e5-a875-25396aa4ac11/e6c7fb7e/result-vtt"
      }
    }

Seznam všech úloh uživatele

Endpoint: /tasks
Metoda: GET

Popis:

Tento endpoint vrací seznam všech úloh, které byly vytvořeny uživatelem. Každá úloha obsahuje základní informace, jako je název, stav, datum vytvoření a informace o nahraném souboru.

Možné odpovědi:

  • 200 OK - Informace o úlohách byly úspěšně načteny.

    {
      "status": "success",
      "num_of_tasks": 45,
      "tasks": [
        {
          "uuid": "0191c1fd-87fd-7258-9656-44bada0a5387",
          "created": "2024-09-05 13:41:43",
          "creditCost": 2,
          "email": "app",
          "fileName": "output.mp3",
          "fileSize": 646793,
          "finished": "2024-09-05 13:42:55",
          "isConfirmed": true,
          "isDuplicate": false,
          "isPaused": false,
          "lengthSeconds": 96,
          "numberOfSpeakers": null,
          "promptDescription": null,
          "promptKeywords": null,
          "promptName": null,
          "promptSpeakers": null,
          "retention": "2025-09-05 13:42:55",
          "started": "2024-09-05 13:42:02",
          "status": "finished",
          "title": "output.mp3",
          "transcribed-txt": "https://cesky.ai/api/v1/01922322-a946-72e5-a875-25396aa4ac11/e6c7fb7e/transcribed-txt",
          "transcribed-json": "https://cesky.ai/api/v1/01922322-a946-72e5-a875-25396aa4ac11/e6c7fb7e/transcribed-json",
          "transcribed-srt": "https://cesky.ai/api/v1/01922322-a946-72e5-a875-25396aa4ac11/e6c7fb7e/transcribed-srt",
          "transcribed-vtt": "https://cesky.ai/api/v1/01922322-a946-72e5-a875-25396aa4ac11/e6c7fb7e/transcribed-vtt",
          "result-txt": "https://cesky.ai/api/v1/01922322-a946-72e5-a875-25396aa4ac11/e6c7fb7e/resutl-txt",
          "result-json": "https://cesky.ai/api/v1/01922322-a946-72e5-a875-25396aa4ac11/e6c7fb7e/result-json",
          "result-srt": "https://cesky.ai/api/v1/01922322-a946-72e5-a875-25396aa4ac11/e6c7fb7e/result-srt",
          "result-vtt": "https://cesky.ai/api/v1/01922322-a946-72e5-a875-25396aa4ac11/e6c7fb7e/result-vtt"
        },
        ...
        more tasks
        ...
      ]
    }

Získání výstupu - s korekturami

Endpoint: /tasks/[uuid]/result.[txt|srt|vtt|json]
Metoda: GET

Popis:

Tento endpoint slouží k získání výsledného výstupu z úlohy s provedenými korekturami. Podle přípony (`txt`, `srt`, `vtt` nebo `json`) se vrátí odpovídající formát souboru (text, titulky nebo strukturovaná data).

Parametry URL:

  • uuid (string, povinný) - Identifikátor úlohy, pro kterou chcete získat výstup.
  • formát (txt|srt|vtt|json, povinný) - Formát požadovaného výstupu. Lze zadat `txt`, `srt`, `vtt` nebo `json`.

Možné odpovědi:

  • 200 OK - Výstup v těle požadavku v požadovaném formátu.
  • 403 Forbidden - Úloha patří jinému uživateli.
  • 404 Not Found - Úloha s daným UUID neexistuje.
  • 409 Conflict - Úloha ještě nebyla dokončena.

Získání výstupu - bez korektur

Endpoint: /tasks/[uuid]/transcribed.[txt|srt|vtt|json]
Metoda: GET

Popis:

Tento endpoint slouží k získání přepsaného výstupu z úlohy bez korektur. Stejně jako u výstupu s korekturami se vrací v zadaném formátu (`txt`, `srt`, `vtt` nebo `json`).

Parametry URL:

  • uuid (string, povinný) - Identifikátor úlohy, pro kterou chcete získat výstup.
  • formát (txt|srt|vtt|json, povinný) - Formát požadovaného výstupu. Lze zadat `txt`, `srt`, `vtt` nebo `json`.

Možné odpovědi:

  • 200 OK - Výstup v těle požadavku v požadovaném formátu.
  • 403 Forbidden - Úloha patří jinému uživateli.
  • 404 Not Found - Úloha s daným UUID neexistuje.
  • 409 Conflict - Úloha ještě nebyla dokončena.

Příklad použití API v jazyce Python

      
import requests
import time

API_BASE_URL = 'https://cesky.ai/api/v1'
API_TOKEN = 'YOUR_API_TOKEN'

def newTask(promptName=None, promptSpeakers=None, promptKeywords=None, promptDescription=None):
    url = f'{API_BASE_URL}/tasks'
    payload = {}
    if promptName:
        payload['promptName'] = promptName
    if promptSpeakers:
        payload['promptSpeakers'] = promptSpeakers
    if promptKeywords:
        payload['promptKeywords'] = promptKeywords
    if promptDescription:
        payload['promptDescription'] = promptDescription
    headers = {'Access-Token': API_TOKEN, 'Accept': 'application/json', 'Content-Type': 'application/json'}
    response = requests.post(url, json=payload, headers=headers)
    response.raise_for_status()
    task = response.json()
    task_uuid = task.get('uuid')
    return task

def uploadTaskData(url, file_path):
    print(f'File {file_path} uploading to {url}')
    with open(file_path, 'rb') as f:
        file_data = f.read()
    headers = {'Access-Token': API_TOKEN, 'Accept': 'application/json', 'Content-Type': 'application/octet-stream'}
    response = requests.post(url, data=file_data, headers=headers)
    response.raise_for_status()
    print(f'File {file_path} uploaded')

def getTask(task_uuid):
    url = f'{API_BASE_URL}/tasks/{task_uuid}'
    headers = {'Access-Token': API_TOKEN, 'Accept': 'application/json'}
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    task = response.json()
    return task

def downloadResult(task_uuid, save_path, format='txt', proofreaded=True):
    result_type = 'result' if proofreaded else 'transcribed'
    url = f'{API_BASE_URL}/tasks/{task_uuid}/{result_type}-{format}'
    headers = {'Access-Token': API_TOKEN}
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    with open(save_path, 'wb') as f:
        f.write(response.content)
    print(f'Downloaded to {save_path}')

def main():
    # 1) Založení nové úlohy
    task = newTask(
        promptName='My Podcast',
        promptSpeakers='John Doe, Jane Smith',
        promptKeywords='AI, Machine Learning',
        promptDescription='Discussion about the latest trends in AI'
    )
    task_uuid = task.get('task').get('uuid')
    print(f'Task created with UUID: {task_uuid}')

    # 2) Nahrání souboru k založené úloze
    uploadTaskData(task.get('uploadUrl'), 'input.mp3')

    # 3) Čekání na dokončení přepisu
    while True:
        task = getTask(task_uuid)
        status = task.get('task').get('status')
        print(f'Task status: {status}')
        if status == 'finished':
            break
        elif status == 'failed':
            print('Task encountered an error.')
            return
        if task.get('task').get('isPaused'):
            print('Task processing is paused.')
        print('Waiting for 1 minute...')
        time.sleep(60)

    # 4) Získání výstupů
    downloadResult(task_uuid, 'transcribed.txt')
    downloadResult(task_uuid, 'transcribed.srt', format='srt')
    downloadResult(task_uuid, 'transcribed.vtt', format='vtt')
    downloadResult(task_uuid, 'transcribed.json', format='json')

    downloadResult(task_uuid, 'result.txt', proofreaded=False)
    downloadResult(task_uuid, 'result.srt', format='srt', proofreaded=False)
    downloadResult(task_uuid, 'result.vtt', format='vtt', proofreaded=False)
    downloadResult(task_uuid, 'result.json', format='json', proofreaded=False)

if __name__ == '__main__':
    main()