Kehittäjän API

Yksi yleinen API kaikkiin tiedostotyönkulkuihin

Converter App tarjoaa kehittäjille tehokkaan tiedostonkäsittelyrajapinnan. Korvaa erilliset työkalut yhdellä APIlla skaalautuvaan asiakirjamuunnokseen, median käsittelyyn, litterointiin ja OCR:ään.

Hanki käyttöoikeus

Converter App API yleiskatsaus

Converter App API tarjoaa kehittäjille kitkattoman, yleiskäyttöisen käyttöliittymän kaikkiin tiedostonkäsittelyn tarpeisiin. Sen sijaan, että integroisitte hajanaisen kokoelman erillisiä työkaluja, sovelluksenne voi kutsua yhtä suorituskykyistä palvelua. Voitte integroida koko muunninsarjamme suoraan taustaprosesseihin, jotta se hoitaa kaiken tavallisista tiedostomuunnoksista vaativiin mediatöihin.

Julkinen perus URL on https://api.converter.app/. Tämän asiakirjan polut käyttävät tätä ulkoisesti tarjottua API juuriosoitetta.

Yleinen kattavuus

Pääset käsiksi kattavaan muunnostyökalujen kirjastoon yhden sujuvan integraation kautta.

Kaksi käsittelytilaa

Valitse synkroniset pyynnöt välittömiä vastauksia varten tai asynkroniset työt suurille tiedostoille ja pitkäkestoisille tehtäville.

Tarpeisiisi räätälöity

Ota yhteyttä, niin voimme tarjota tarpeisiisi räätälöidyn suunnitelman lyömättömään hintaan.

Asiakirjat Kuvat Ääni Video Teksti Arkistot

Tutustu tuettuihin muunnoksiin (ei avainta tarvita)

Käytä julkista pairs-päätepistettä yksinkertaisimpana yhteystestinä. Se ei vaadi API avainta ja palauttaa koko luettelon alustalla saatavilla olevista tuetuista muunnospareista.

HAE /public/pairs

Tämä päätepiste on avoin, joten kehittäjät voivat tarkastella yleistä muunnoskatalogia ennen API avaimen pyytämistä tai määrittämistä.

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

Esimerkkivastaus

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

Todennus & pääsynhallinta

Kehittäjät todentavat itsensä välittämällä API avaimensa HTTP otsakkeessa X API Key. Julkinen päätepiste /public/pairs on ainoa tällä sivulla oleva päätepiste, joka ei vaadi avainta.

Hallinta	Miten se toimii	Kehittäjille suunnattu vaikutus
`X-API-Key`	Lähetä avain HTTP pyyntöotsakkeena.	Vaaditaan seuraaville: `/pairs`, `/convert/sync`, `/convert`, `/progress/{jobid}` ja `/download/{jobid}`.
Käyttökiintiöt	Jokaisella avaimella on numeerinen muuntokiintiö. Kiintiö pienenee, kun muuntotehtäviä luodaan.	`-1` -kiintiö myöntää rajoittamattoman määrän muunnoksia. Muut arvot osoittavat jäljellä olevien sallittujen muunnosten määrän.
Sallitut parit	Avaimet voidaan rajoittaa tiettyihin muunnostyyppeihin, kuten `mp42mp3`, tai niille voidaan myöntää käyttöoikeus kaikkiin `all`-tuettuihin pareihin.	`/pairs` palauttaa vain parit, joita avaimesi saa käyttää, ja sen listan ulkopuoliset muunnospyynnöt hylätään.

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. Synkroninen muunnos

POST /convert/sync

Käytä synkronista muunnosta, kun haluat välittömän tuloksen samassa HTTP vastauksessa. Pyyntö pysyy avoinna, kun API käynnistää muunnostyön ja odottaa sen valmistumista, enintään 30 minuuttia.

Lomakekenttä	Tyyppi	Kuvaus
`target_format`	merkkijono	Pyydetty tulosteen tiedostopääte, kuten `pdf`, `docx`, `mp3` tai `jpg`.
`files`	tiedosto[]	Yksi tai useampi ladattu lähdetiedosto. API määrittää lähdeformaatin ladatun tiedoston nimestä.

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)

Vastaus suoratoistaa muunnetun tiedoston suoraan. Jos muunnos tuottaa useita tiedostoja, API palauttaa .zip-arkiston.

3. Asynkroninen muunnos

POST /convert

Käytä asynkronista muunnosta suurille tiedostoille, eräajoon, pitkään kestäville ääni- tai videotöille tai tuotantosovelluksiin, joiden ei pidä pitää latauspyyntöjä auki työn ollessa käynnissä.

Lomakekenttä	Tyyppi	Kuvaus
`target_format`	merkkijono	Haluttu tulostusmuoto. Lähde- ja kohdemuoto muodostavat muunnosparin, esimerkiksi `mp42mp3`.
`files`	tiedosto[]	Yksi tai useampi tiedosto muunnettavaksi.

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

Onnistumisvastaus

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

4. Tilan seuranta

Hae /progress/{jobid}

Kysely tämän päätepisteen tilasta asynkronisen työn luomisen jälkeen. Se palauttaa työn tilan, numeerisen edistymisarvon välillä 0.0–1.0 sekä virhetiedot, jos muunnos epäonnistui.

Otsikko	Kuvaus
`X-API-Key`	Kehittäjän API avain.

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
}

Mahdolliset tilat ovat processing, completed ja failed. Edistyminen on luku välillä 0.0 ja 1.0.

5. Tiedoston nouto

HAE /download/{jobid}

Kun asynkroninen tehtävä saavuttaa tilan completed, hae muunnettu tulos samalla API avaimella, jota käytettiin tehtävän luomiseen.

Tulostyyppi	Käyttäytyminen
Yksi tulostiedosto	API suoratoistaa muunnetun tiedoston suoraan.
`resultfile` manifesti	Jos työtehtävä tarjoaa tulosmanifestin, API palauttaa kyseisessä manifestissa määritetyn tiedoston.
Useita tulostiedostoja	API pakkaa luodut tiedostot lennossa `.zip`-arkistoon.

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)

Kehittäjän työnkulun yhteenveto

API tukee kahta integrointimallia, joten kehittäjät voivat valita kuhunkin käyttötapaukseen sopivan toiminnan.

Kulku	Pyyntömalli	Paras käyttökohde
Nopea synkronointivirta	`POST /convert/sync` palauttaa muunnetun tiedoston samassa vastauksessa.	Pienet tiedostot, komentoriviskriptit, prototyypit ja yksinkertaiset palvelinpuolen automaatiot.
Vankka asynkroninen työnkulku	`POST /convert`, sitten kysy tilaa `GET /progress/{jobid}`, sitten kutsu `GET /download/{jobid}`.	Suuret video- tai äänitiedostot, erämuunnos, verkkosovellusten taustajärjestelmät ja uudelleenyrityksiä kestävät tuotantojärjestelmät.

Asynkronisen työnkulun esimerkki

# 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)

Virhevastaukset

Virheet palautetaan JSON muodossa, jossa on detail-kenttä, ja käytetään tavallisia HTTP tilakoodeja.

Tila	Yleinen syy
`400`	Puuttuvat tiedostot, puuttuva `target_format`, tuetun työtehtävän tunnisteen muotoa ei tueta tai pyyntösyöte on virheellinen.
`401`	Puuttuva tai virheellinen `X API Key`.
`403`	API avaimella ei ole sallittua käyttää pyydettyä muunnosparia.
`404`	Pyydettyä tehtävää tai luotua tulostiedostoa ei ole saatavilla.
`409`	Muuntaus on yhä käynnissä, kun lataus pyydetään.
`429`	API avaimella ei ole enää jäljellä kiintiötä.
`500`	Muunnosta ei voitu valmistella tai suorittaa loppuun palvelimen käsittelyvirheen vuoksi.

{
  "detail": "This API key is not authorized for mp42mp3 conversions."
}

Yksi yleinen API kaikkiin tiedostotyönkulkuihin

Converter App API yleiskatsaus

Tutustu tuettuihin muunnoksiin (ei avainta tarvita)

JavaScript

Python

Esimerkkivastaus

Todennus & pääsynhallinta

JavaScript

Python

2. Synkroninen muunnos

JavaScript

Python

3. Asynkroninen muunnos

cURL

JavaScript

Python

Onnistumisvastaus

4. Tilan seuranta

JavaScript

Python

5. Tiedoston nouto

JavaScript

Python

Kehittäjän työnkulun yhteenveto

Asynkronisen työnkulun esimerkki

JavaScript

Python

Virhevastaukset

Tietosuoja ja ehdot

Contact