Vývojárske API

Jedno univerzálne API pre každý pracovný postup so súbormi

Converter App poskytuje vývojárom vysokovýkonné rozhranie na spracovanie súborov. Namiesto samostatných nástrojov použite jedno API na škálovateľnú konverziu dokumentov, spracovanie médií, prepis a OCR.

Získať prístup

Prehľad API Converter App

API Converter App poskytuje vývojárom bezproblémové univerzálne rozhranie pre všetky potreby spracovania súborov. Namiesto integrácie roztrieštenej zbierky samostatných nástrojov môže vaša aplikácia volať jedinú vysokovýkonnú službu. Našu kompletnú sadu nástrojov na konverziu môžete priamo integrovať do backendových pracovných postupov, aby zvládala všetko od štandardných zmien súborov až po náročné mediálne úlohy.

Verejná základná adresa URL je https://api.converter.app/. Cesty v tomto dokumente používajú tento externe poskytovaný koreň API.

Univerzálne pokrytie

Získajte prístup k celej knižnici nástrojov na konverziu prostredníctvom jednej zjednodušenej integrácie.

Dva režimy spracovania

Zvoľte synchronné požiadavky pre okamžité odpovede alebo asynchrónne úlohy pre veľké súbory a úlohy s dlhším priebehom.

Prispôsobené vašim potrebám

Kontaktujte nás a pripravíme plán prispôsobený vašim potrebám za neprekonateľnú cenu.

Dokumenty Obrázky Zvuk Video Text Archívy

Objavte podporované konverzie (kľúč nie je potrebný)

Použite verejný endpoint pairs ako najjednoduchší test konektivity. Nevyžaduje API kľúč a vráti celý zoznam podporovaných párov konverzie dostupných na platforme.

ZÍSKAŤ /public/pairs

Tento endpoint je otvorený, aby si vývojári mohli prezrieť univerzálny katalóg konverzií pred požiadaním o API kľúč alebo jeho nastavením.

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'])

Príklad odpovede

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

Autentifikácia & riadenie prístupu

Vývojári sa overujú odoslaním svojho API kľúča v hlavičke HTTP X API Key. Verejný endpoint /public/pairs je jediný endpoint na tejto stránke, ktorý nevyžaduje kľúč.

OvládanieAko to fungujeVplyv pre vývojárov
X-API-KeyOdošlite kľúč ako hlavičku HTTP požiadavky.Vyžadované pre /pairs, /convert/sync, /convert, /progress/{jobid} a /download/{jobid}.
Kvóty používaniaKaždý kľúč má numerickú kvótu na konverziu. Kvóta sa znižuje, keď sa vytvoria úlohy konverzie.Kvóta -1 poskytuje neobmedzený počet konverzií. Ostatné hodnoty predstavujú zostávajúci počet povolených konverzií.
Povolené páryKľúče môžu byť obmedzené na konkrétne typy konverzie, napríklad mp42mp3, alebo im môže byť udelený prístup ku všetkým podporovaným párom all./pairs vráti iba páry, ktoré je Váš kľúč oprávnený používať, a požiadavky na konverziu mimo tohto zoznamu sa zamietnu.
 
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. Syntická konverzia

POST /convert/sync

Použite synchrónnu konverziu, keď chcete okamžitý výsledok v rámci rovnakej HTTP odpovede. Požiadavka zostane otvorená, zatiaľ čo API spustí úlohu konverzie a čaká na jej dokončenie, najviac 30 minút.

Pole formuláraTypPopis
target_formatreťazecPožadovaná výstupná prípona, ako napríklad pdf, docx, mp3 alebo jpg.
filessúbor[]Jeden alebo viac nahraných zdrojových súborov. API určí zdrojový formát podľa názvu nahraného súboru.
 
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)

Odpoveď priamo streamuje konvertovaný súbor. Ak konverzia vytvorí viacero súborov, API vráti archív .zip.

3. Asynchrónna konverzia

PRÍSPEVOK /convert

Použite asynchrónnu konverziu pre veľké súbory, dávkové spracovanie, dlhšie trvajúce úlohy s audio alebo video súbormi alebo produkčné aplikácie, ktoré by nemali ponechávať požiadavky na nahrávanie otvorené, kým prebieha spracovanie.

Pole formuláraTypPopis
target_formatreťazecPožadovaný výstupný formát. Zdrojový a cieľový formát tvoria dvojicu konverzie, napríklad mp42mp3.
filessúbor[]Jeden alebo viac súborov na konverziu.

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'])

Odpoveď s úspechom

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

4. Sledovanie stavu

ZÍSKAŤ /progress/{jobid}

Po vytvorení asynchrónnej úlohy tento endpoint opakovane dopytujte. Vráti stav úlohy, číselnú hodnotu priebehu od 0.0 do 1.0 a podrobnosti o chybe, ak sa konverzia nepodarila.

HlavičkaPopis
X-API-KeyVáš vývojársky API kľúč.
 
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 sú processing, completed a failed. Postup je číslo medzi 0.0 a 1.0.

5. Vyhľadanie súboru

ZÍSKAŤ /download/{jobid}

Keď asynchrónna úloha dosiahne stav completed, získajte skonvertovaný výstup pomocou toho istého API kľúča, ktorý bol použitý na vytvorenie úlohy.

Typ výsledkuSprávanie
Jeden výstupný súborRozhranie API streamuje skonvertovaný súbor priamo.
resultfile manifest Ak úloha poskytne manifest výsledkov, API vráti súbor uvedený v tomto manifeste.
Viacero výstupných súborovBalíky API priebežne zoskupujú vygenerované súbory do archívu .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)

Zhrnutie pracovného postupu vývojára

Rozhranie API podporuje dva integračné vzory, takže si vývojári môžu zvoliť správne správanie pre každý prípad použitia.

TokVzor požiadavkyNajlepšie pre
Rýchly synchronizačný postupPOST /convert/sync vráti skonvertovaný súbor v tej istej odpovedi.Malé súbory, skripty príkazového riadka, prototypy a jednoduché serverové automatizácie.
Odolný asynchrónny tokPOST /convert, potom opakovane dotazujte GET /progress/{jobid} a nakoniec zavolajte GET /download/{jobid}.Veľké video alebo audio súbory, hromadná konverzia, backendy webových aplikácií a produkčné systémy vhodné na opakované pokusy.

Príklad asynchrónneho 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é odpovede

Chyby sa vracajú ako JSON s poľom detail a používajú štandardné HTTP stavové kódy.

StavBežná príčina
400Chýbajúce súbory, chýbajúci target_format, nepodporovaný formát ID úlohy alebo neplatný vstup požiadavky.
401Chýba alebo je neplatný X API Key.
403Kľúč API nemá povolenie používať požadovanú konverznú dvojicu.
404Požadovaná úloha alebo vygenerovaný výsledný súbor nie je k dispozícii.
409Konverzia sa stále spracúva, keď je vyžiadané stiahnutie.
429Kľúču API už nezostáva žiadna kvóta.
500Konverzia sa nepodarilo pripraviť ani dokončiť kvôli chybe pri spracovaní na strane servera.
 
{
  "detail": "This API key is not authorized for mp42mp3 conversions."
}