適用於每種檔案工作流程的單一通用 API

此端點是開放的，因此開發者在申請或設定 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'])

範例回應

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

當您希望在同一個 HTTP 回應中立即取得結果時，請使用同步轉換。請求會保持開啟，直到 API 啟動轉換工作並等待完成，最長可達 30 分鐘。

表單欄位	類型	說明
target_format	字串	所要求的輸出副檔名，例如 pdf、docx、mp3 或 jpg。
files	file[]	一個或多個已上傳的來源檔案。API 會根據已上傳的檔案名稱判定來源格式。

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)

回應會直接串流轉換後的檔案。如果轉換產生多個檔案，API 會回傳 .zip 壓縮檔。

對於大型檔案、批次處理、長時間執行的音訊或影片任務，或不應在工作執行期間保持上傳請求開啟的正式應用程式，請使用非同步轉換。

表單欄位	類型	說明
target_format	字串	所需的輸出格式。來源與目標構成轉換組合，例如 mp42mp3。
files	file[]	要轉換的一個或多個檔案。

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

成功回應

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

建立非同步工作後，請輪詢此端點。它會回傳工作狀態、從 0.0 到 1.0 的數值進度，以及若轉換失敗時的錯誤詳細資訊。

頁首	說明
X-API-Key	您的開發人員 API 金鑰。

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
}

可能的狀態為 processing、completed 與 failed。進度是介於 0.0 和 1.0 之間的數字。

一旦非同步工作達到 completed，請使用建立該工作的相同 API 金鑰擷取已轉換的輸出。

結果類型	行為
單一輸出檔案	API 會直接串流轉換後的檔案。
結果檔案 清單	如果工作提供結果清單，API 會傳回該清單中指定的檔案。
多個輸出檔案	API 會在處理時將生成的檔案打包成 .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)