Rozhraní API pro vývojáře

Jedno univerzální API pro každý souborový workflow

Converter App poskytuje vývojářům vysoce výkonné rozhraní pro zpracování souborů. Nahraďte samostatné nástroje jediným API pro škálovatelný převod dokumentů, zpracování médií, přepis a OCR.

Získat přístup

Přehled API Converter App

API Converter App poskytuje vývojářům bezproblémové a univerzální rozhraní pro všechny potřeby zpracování souborů. Místo integrace roztříštěné sady samostatných nástrojů může vaše aplikace volat jedinou vysoce výkonnou službu. Celou naši sadu převodníků můžete integrovat přímo do backendových workflow a zvládnout vše od běžných změn souborů až po náročné mediální úlohy.

Veřejná základní adresa URL je https://api.converter.app/. Cesty v tomto dokumentu používají tento externě poskytovaný kořen API.

Univerzální pokrytí

Získejte přístup k celé knihovně nástrojů pro převod prostřednictvím jediné zjednodušené integrace.

Dva způsoby zpracování

Zvolte synchronní požadavky pro okamžité odpovědi nebo asynchronní úlohy pro velké soubory a dlouho běžící úlohy.

Přizpůsobeno vašim potřebám

Ozvěte se nám a můžeme vám nabídnout plán přizpůsobený vašim potřebám za bezkonkurenční cenu.

Dokumenty Obrázky Zvuk Video Text Archivy

Objevte podporované převody (není potřeba žádný klíč)

Použijte veřejný endpoint pairs jako nejjednodušší test připojení. Nevyžaduje API klíč a vrací kompletní seznam podporovaných převodních dvojic dostupných na platformě.

ZÍSKAT /public/pairs

Tento endpoint je otevřený, aby si vývojáři mohli prohlédnout univerzální katalog převodů před požádáním o klíč API nebo jeho konfigurací.

curl "https://api.converter.app/public/pairs"

JavaScript

const response = await fetch('https://api.converter.app/public/pairs');
const pairs = await response.json();
console.log(pairs.supported_pairs);

Python

import requests

response = requests.get('https://api.converter.app/public/pairs')
response.raise_for_status()
pairs = response.json()
print(pairs['supported_pairs'])

Příklad odpovědi

{
  "supported_pairs": [
    { "from": "mp3", "to": "text" },
    { "from": "mp4", "to": "mp3" },
    { "from": "mov", "to": "mp4" },
    { "from": "wav", "to": "mp3" },
    { "from": "mkv", "to": "mp4" }
  ]
}

Ověřování & řízení přístupu

Vývojáři se ověřují předáním svého API klíče v HTTP hlavičce X API Key. Veřejný endpoint /public/pairs je na této stránce jediným endpointem, který nevyžaduje klíč.

OvládáníJak to fungujeDopad pro vývojáře
X-API-KeyOdešlete klíč jako hlavičku HTTP požadavku.Vyžadováno pro /pairs, /convert/sync, /convert, /progress/{jobid} a /download/{jobid}.
Limity používáníKaždý klíč má číselnou kvótu pro převod. Tato kvóta se snižuje při vytváření úloh převodu.Kvóta -1 poskytuje neomezený počet převodů. Ostatní hodnoty představují zbývající povolený počet převodů.
Povolené dvojiceKlíče lze omezit na konkrétní typy převodu, například mp42mp3, nebo jim lze udělit přístup ke všem podporovaným dvojicím all./pairs vrací pouze dvojice, které je váš klíč oprávněn používat, a požadavky na převod mimo tento seznam jsou zamítnuty.
 
curl "https://api.converter.app/pairs" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const response = await fetch('https://api.converter.app/pairs', {
  headers: {
    'X-API-Key': apiKey
  }
});

const pairs = await response.json();
console.log(pairs);

Python

import requests

headers = {'X-API-Key': 'YOUR_API_KEY'}
response = requests.get('https://api.converter.app/pairs', headers=headers)
response.raise_for_status()
print(response.json())

2. Synchronní převod

POŠTOVNÍ SCHRÁNKA /convert/sync

Použijte synchronní převod, pokud chcete okamžitý výsledek ve stejné HTTP odpovědi. Požadavek zůstane otevřený, zatímco API spustí úlohu převodu a čeká na její dokončení, maximálně 30 minut.

Pole formulářeTypPopis
target_formatřetězecPožadovaná výstupní přípona, například pdf, docx, mp3 nebo jpg.
filessoubor[]Jeden nebo více nahraných zdrojových souborů. Rozhraní API určí zdrojový formát podle názvu nahraného souboru.
 
curl -X POST "https://api.converter.app/convert/sync" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "target_format=pdf" \
  -F "files=@/path/to/document.docx" \
  -o converted.pdf

JavaScript

const form = new FormData();
form.append('target_format', 'pdf');
form.append('files', fileInput.files[0]);

const response = await fetch('https://api.converter.app/convert/sync', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey
  },
  body: form
});

const convertedFile = await response.blob();

Python

import requests

headers = {'X-API-Key': 'YOUR_API_KEY'}
data = {'target_format': 'pdf'}

with open('/path/to/document.docx', 'rb') as document:
    files = {'files': document}
    response = requests.post(
        'https://api.converter.app/convert/sync',
        headers=headers,
        data=data,
        files=files
    )

response.raise_for_status()
with open('converted.pdf', 'wb') as output:
    output.write(response.content)

Odpověď přímo streamuje převedený soubor. Pokud převod vytvoří více souborů, API vrátí archiv .zip.

3. Asynchronní převod

PŘÍSPĚVEK /convert

Použijte asynchronní převod pro velké soubory, dávkové zpracování, dlouhotrvající úlohy s audiem nebo videem či produkční aplikace, které by neměly ponechávat požadavky na nahrání otevřené, zatímco práce probíhá.

Pole formulářeTypPopis
target_formatřetězecPožadovaný výstupní formát. Zdrojový a cílový formát tvoří dvojici převodu, například mp42mp3.
filessoubor[]Jeden nebo více souborů k převodu.

cURL

curl -X POST "https://api.converter.app/convert" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "target_format=mp3" \
  -F "files=@/path/to/video.mp4"

JavaScript

const form = new FormData();
form.append('target_format', 'mp3');
form.append('files', fileInput.files[0]);

const response = await fetch('https://api.converter.app/convert', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey
  },
  body: form
});

const job = await response.json();
console.log(job.jobid, job.remaining_quota);

Python

import requests

headers = {'X-API-Key': 'YOUR_API_KEY'}
data = {'target_format': 'mp3'}

with open('/path/to/video.mp4', 'rb') as video:
    files = {'files': video}
    response = requests.post(
        'https://api.converter.app/convert',
        headers=headers,
        data=data,
        files=files
    )

response.raise_for_status()
job = response.json()
print(job['jobid'], job['remaining_quota'])

Úspěšná odpověď

{
  "status": "success",
  "jobid": "b3f6b2e8f5c34c4ab01c93c4d1b2f9e8",
  "pair": "mp42mp3",
  "remaining_quota": 42
}

4. Sledování stavu

ZÍSKAT /progress/{jobid}

Po vytvoření asynchronní úlohy tento endpoint pravidelně dotazujte. Vrací stav úlohy, číselnou hodnotu průběhu od 0.0 do 1.0 a podrobnosti o chybě, pokud převod selhal.

ZáhlavíPopis
X-API-KeyVáš vývojářský API klíč.
 
curl "https://api.converter.app/progress/b3f6b2e8f5c34c4ab01c93c4d1b2f9e8" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const response = await fetch('https://api.converter.app/progress/b3f6b2e8f5c34c4ab01c93c4d1b2f9e8', {
  headers: {
    'X-API-Key': apiKey
  }
});

const progress = await response.json();
console.log(progress.status, progress.progress);

Python

import requests

headers = {'X-API-Key': 'YOUR_API_KEY'}
response = requests.get(
    'https://api.converter.app/progress/b3f6b2e8f5c34c4ab01c93c4d1b2f9e8',
    headers=headers
)
response.raise_for_status()
progress = response.json()
print(progress['status'], progress['progress'])
{
  "jobid": "b3f6b2e8f5c34c4ab01c93c4d1b2f9e8",
  "progress": 1.0,
  "status": "completed",
  "error": null
}

Možné stavy jsou processing, completed a failed. Průběh je číslo mezi 0.0 a 1.0.

5. Získání souboru

ZÍSKAT /download/{jobid}

Jakmile asynchronní úloha dosáhne stavu completed, načtěte převedený výstup pomocí stejného API klíče, který byl použit k vytvoření úlohy.

Typ výsledkuChování
Jeden výstupní souborRozhraní API streamuje převedený soubor přímo.
manifest resultfilePokud úloha poskytne manifest výsledku, API vrátí soubor určený tímto manifestem.
Více výstupních souborůRozhraní API průběžně balí vygenerované soubory do archivu .zip.
 
curl -L "https://api.converter.app/download/b3f6b2e8f5c34c4ab01c93c4d1b2f9e8" \
  -H "X-API-Key: YOUR_API_KEY" \
  -o converted-output.zip

JavaScript

const response = await fetch('https://api.converter.app/download/b3f6b2e8f5c34c4ab01c93c4d1b2f9e8', {
  headers: {
    'X-API-Key': apiKey
  }
});

const file = await response.blob();

Python

import requests

headers = {'X-API-Key': 'YOUR_API_KEY'}
response = requests.get(
    'https://api.converter.app/download/b3f6b2e8f5c34c4ab01c93c4d1b2f9e8',
    headers=headers
)
response.raise_for_status()

with open('converted-output.zip', 'wb') as output:
    output.write(response.content)

Shrnutí pracovního postupu vývojáře

Rozhraní API podporuje dva integrační vzory, takže si vývojáři mohou pro každý případ použití zvolit vhodné chování.

TokVzor požadavkuNejlepší pro
Rychlý synchronizační procesPOST /convert/sync vrátí převedený soubor ve stejné odpovědi.Malé soubory, skripty z příkazové řádky, prototypy a jednoduché serverové automatizace.
Robustní asynchronní tokPOST /convert, poté dotazujte GET /progress/{jobid} a nakonec zavolejte GET /download/{jobid}.Velké video nebo audio soubory, dávkové převody, backendy webových aplikací a produkční systémy vhodné pro opakované pokusy.

Příklad asynchronního toku

# 1. Start the job
curl -X POST "https://api.converter.app/convert" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "target_format=mp3" \
  -F "files=@/path/to/video.mp4"

# 2. Poll until completed
curl "https://api.converter.app/progress/JOBID" \
  -H "X-API-Key: YOUR_API_KEY"

# 3. Download the finished output
curl -L "https://api.converter.app/download/JOBID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -o result.mp3

JavaScript

const form = new FormData();
form.append('target_format', 'mp3');
form.append('files', fileInput.files[0]);

const createResponse = await fetch('https://api.converter.app/convert', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey
  },
  body: form
});
const job = await createResponse.json();

const progressResponse = await fetch(`https://api.converter.app/progress/${job.jobid}`, {
  headers: {
    'X-API-Key': apiKey
  }
});
const progress = await progressResponse.json();

if (progress.status === 'completed') {
  const downloadResponse = await fetch(`https://api.converter.app/download/${job.jobid}`, {
    headers: {
      'X-API-Key': apiKey
    }
  });
  const result = await downloadResponse.blob();
}

Python

import requests

headers = {'X-API-Key': 'YOUR_API_KEY'}
data = {'target_format': 'mp3'}

with open('/path/to/video.mp4', 'rb') as video:
    files = {'files': video}
    create_response = requests.post(
        'https://api.converter.app/convert',
        headers=headers,
        data=data,
        files=files
    )

create_response.raise_for_status()
job = create_response.json()

progress_response = requests.get(
    f"https://api.converter.app/progress/{job['jobid']}",
    headers=headers
)
progress_response.raise_for_status()
progress = progress_response.json()

if progress['status'] == 'completed':
    download_response = requests.get(
        f"https://api.converter.app/download/{job['jobid']}",
        headers=headers
    )
    download_response.raise_for_status()
    with open('result.mp3', 'wb') as output:
        output.write(download_response.content)

Chybové odpovědi

Chyby se vracejí jako JSON s polem detail a používají standardní HTTP stavové kódy.

StavSpolečná příčina
400Chybějící soubory, chybějící target_format, nepodporovaný formát ID úlohy nebo neplatný vstup požadavku.
401Chybí nebo je neplatný X API Key.
403Klíč API nemá oprávnění používat požadovanou dvojici převodu.
404Požadovaná úloha nebo vygenerovaný výsledný soubor není k dispozici.
409Převod je stále zpracováván, když je vyžádáno stažení.
429Klíči API již nezbývá žádná kvóta.
500Konverzi nebylo možné připravit ani dokončit kvůli chybě zpracování na straně serveru.
 
{
  "detail": "This API key is not authorized for mp42mp3 conversions."
}