API per sviluppatori

Un’unica API universale per ogni flusso di lavoro dei file

Converter App offre agli sviluppatori un'interfaccia di elaborazione file ad alte prestazioni. Sostituite strumenti separati con una sola API per la conversione scalabile di documenti, l'elaborazione multimediale, la trascrizione e l'OCR.

Ottieni accesso

Panoramica API di Converter App

La API di Converter App offre agli sviluppatori un’interfaccia universale e senza attriti per tutte le esigenze di elaborazione dei file. Invece di integrare una raccolta frammentata di strumenti separati, la vostra applicazione può chiamare un unico servizio ad alte prestazioni. Potete integrare direttamente nella logica backend la nostra suite completa di conversione per gestire di tutto, dalle normali conversioni di file ai lavori multimediali più impegnativi.

L'URL base pubblica è https://api.converter.app/. I percorsi in questo documento utilizzano questa radice API servita dall'esterno.

Copertura universale

Accedete a una libreria completa di strumenti di conversione tramite un’unica integrazione semplificata.

Due modalità di elaborazione

Scegli richieste sincrone per risposte immediate oppure processi asincroni per file di grandi dimensioni e attività a lunga esecuzione.

Su misura per le Sue esigenze

Contattateci e possiamo offrirvi un piano su misura per le vostre esigenze a una tariffa imbattibile.

Documenti Immagini Audio Video Testo Archivi

Scopri le conversioni supportate (non serve alcuna chiave)

Utilizzi l’endpoint pubblico pairs come test di connettività più semplice. Non richiede una chiave API e restituisce l’elenco completo delle coppie di conversione supportate disponibili sulla piattaforma.

OTTIENI /public/pairs

Questo endpoint è aperto, così gli sviluppatori possono consultare il catalogo universale di conversione prima di richiedere o configurare una chiave API.

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

Esempio di risposta

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

Autenticazione e controllo degli accessi

Gli sviluppatori si autenticano passando la propria chiave API nell'intestazione HTTP X API Key. L'endpoint pubblico /public/pairs è l'unico endpoint di questa pagina che non richiede una chiave.

Controllo	Come funziona	Impatto per gli sviluppatori
`X-API-Key`	Invii la chiave come intestazione della richiesta HTTP.	Richiesto per `/pairs`, `/convert/sync`, `/convert`, `/progress/{jobid}` e `/download/{jobid}`.
Quote di utilizzo	Ogni chiave ha una quota numerica di conversione. La quota diminuisce quando vengono creati task di conversione.	Una quota di `-1` concede conversioni illimitate. Gli altri valori rappresentano le conversioni consentite rimanenti.
Coppie consentite	Le chiavi possono essere limitate a tipi di conversione specifici, come `mp42mp3`, oppure ricevere accesso a `all` le coppie supportate.	`/pairs` restituisce solo le coppie che la sua chiave è autorizzata a usare, e le richieste di conversione al di fuori di quell'elenco vengono rifiutate.

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. Conversione sincrona

POST /convert/sync

Utilizzi la conversione sincrona quando desidera un risultato immediato nella stessa risposta HTTP. La richiesta rimane aperta mentre l'API avvia il processo di conversione e attende il completamento, fino a 30 minuti.

Campo del modulo	Tipo	Descrizione
`target_format`	string	L’estensione di output richiesta, ad esempio `pdf`, `docx`, `mp3` o `jpg`.
`files`	file[]	Uno o più file sorgente caricati. L'API determina il formato di origine dal nome del file caricato.

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)

La risposta trasmette direttamente il file convertito in streaming. Se la conversione produce più file, l'API restituisce un archivio .zip.

3. Conversione asincrona

POST /convert

Utilizzate la conversione asincrona per file di grandi dimensioni, l’elaborazione in batch, attività audio o video di lunga durata o applicazioni di produzione che non devono mantenere aperte le richieste di caricamento mentre il lavoro è in esecuzione.

Campo del modulo	Tipo	Descrizione
`target_format`	string	Il formato di output desiderato. Il formato di origine e quello di destinazione formano la coppia di conversione, ad esempio `mp42mp3`.
`files`	file[]	Uno o più file da convertire.

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

Risposta di successo

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

4. Monitoraggio dello stato

OTTIENI /progress/{jobid}

Interrogare questo endpoint dopo aver creato un processo asincrono. Restituisce lo stato del processo, un valore numerico di avanzamento da 0.0 a 1.0 ed eventuali dettagli di errore se la conversione non è riuscita.

Intestazione	Descrizione
`X-API-Key`	La sua chiave API per sviluppatori.

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
}

Gli stati possibili sono processing, completed e failed. L’avanzamento è un numero compreso tra 0.0 e 1.0.

5. Recupero file

OTTIENI /download/{jobid}

Una volta che un lavoro asincrono raggiunge completed, recuperi l’output convertito con la stessa chiave API usata per creare il lavoro.

Tipo di risultato	Comportamento
File di output singolo	L’API trasmette direttamente il file convertito.
manifesto di `resultfile`	Se il processo fornisce un manifest dei risultati, l'API restituisce il file specificato in quel manifest.
Più file di output	L'API raggruppa i file generati in un archivio `.zip` al volo.

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)

Riepilogo del flusso di lavoro dello sviluppatore

L'API supporta due modelli di integrazione, così gli sviluppatori possono scegliere il comportamento più adatto a ogni caso d'uso.

Flusso	Schema della richiesta	Ideale per
Flusso di sincronizzazione rapida	`POST /convert/sync` restituisce il file convertito nella stessa risposta.	File di piccole dimensioni, script da riga di comando, prototipi e semplici automazioni lato server.
Flusso asincrono robusto	`POST /convert`, quindi interroghi `GET /progress/{jobid}`, poi chiami `GET /download/{jobid}`.	File video o audio di grandi dimensioni, conversione in batch, backend di applicazioni web e sistemi di produzione adatti ai tentativi ripetuti.

Esempio di flusso asincrono

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

Risposte di errore

Gli errori vengono restituiti come JSON con un campo detail, utilizzando i codici di stato HTTP standard.

Stato	Causa comune
`400`	File mancanti, `target_format` mancante, formato dell'ID del lavoro non supportato o input della richiesta non valido.
`401`	Manca `X API Key` oppure non è valido.
`403`	La chiave API non è autorizzata a utilizzare la coppia di conversione richiesta.
`404`	Il lavoro richiesto o il file risultato generato non è disponibile.
`409`	La conversione è ancora in corso quando viene richiesto il download.
`429`	La chiave API non ha più quota disponibile.
`500`	La conversione non è stata preparata o completata a causa di un errore di elaborazione lato server.

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

Un’unica API universale per ogni flusso di lavoro dei file

Panoramica API di Converter App

Scopri le conversioni supportate (non serve alcuna chiave)

JavaScript

Python

Esempio di risposta

Autenticazione e controllo degli accessi

JavaScript

Python

2. Conversione sincrona

JavaScript

Python

3. Conversione asincrona

cURL

JavaScript

Python

Risposta di successo

4. Monitoraggio dello stato

JavaScript

Python

5. Recupero file

JavaScript

Python

Riepilogo del flusso di lavoro dello sviluppatore

Esempio di flusso asincrono

JavaScript

Python

Risposte di errore

Privacy e termini

Contact