파일변환 서비스 restapi 예제

백엔드&인프라 추종자·2025년 11월 5일

mediaforge 개발 프로젝트

목록 보기

6/22

좋은 질문입니다, 정우님.
Convertio나 CloudConvert 같은 “파일 변환 API 서비스”들은 REST API 기반으로 파일을 업로드하고, 변환이 완료되면 다운로드 링크를 받는 구조로 되어 있습니다.
아래는 그 일반적인 흐름과 실제 예시를 단계별로 설명드리겠습니다.

🔹 1. 기본 구조 요약

파일 변환 API 서비스의 전형적인 요청-응답 구조는 다음과 같습니다:

단계	설명	HTTP 메서드	예시 엔드포인트
1	변환 작업 생성	`POST`	`/convert` 또는 `/v2/jobs`
2	파일 업로드	`PUT` or `POST`	`/upload` 또는 presigned URL
3	변환 진행 상태 확인	`GET`	`/convert/:id`
4	변환 결과 다운로드	`GET`	변환된 파일 URL

🔹 2. 예시: CloudConvert REST API 구조 (가장 대표적인 모델)

POST https://api.cloudconvert.com/v2/jobs
Authorization: Bearer <API_KEY>
Content-Type: application/json

요청 바디 예시:

{
  "tasks": {
    "import-my-file": {
      "operation": "import/upload"
    },
    "convert-my-file": {
      "operation": "convert",
      "input": "import-my-file",
      "input_format": "mp4",
      "output_format": "mp3"
    },
    "export-my-file": {
      "operation": "export/url",
      "input": "convert-my-file"
    }
  }
}

응답 예시:

{
  "data": {
    "id": "job-1234567890",
    "tasks": [
      {
        "id": "task-import-my-file",
        "result": {
          "form": {
            "url": "https://storage.cloudconvert.com/upload/abcdef",
            "parameters": {}
          }
        }
      }
    ]
  }
}

🔹 3. 실제 파일 업로드 단계

import/upload 작업에서 받은 URL에 POST 요청으로 파일을 업로드합니다.

curl -X POST "https://storage.cloudconvert.com/upload/abcdef" \
  -F "file=@input.mp4"

이렇게 업로드하면 CloudConvert가 해당 파일을 변환 작업에 연결합니다.

🔹 4. 변환 진행 상태 확인

GET https://api.cloudconvert.com/v2/jobs/job-1234567890
Authorization: Bearer <API_KEY>

응답의 "status": "finished"가 되면 변환 완료입니다.
완료 후 export/url 작업에 다운로드 가능한 URL이 포함됩니다.

🔹 5. 변환 파일 다운로드

curl -L -o output.mp3 "https://storage.cloudconvert.com/exports/xyz123.mp3"

🔹 6. Convertio 의 REST API 패턴 (단순형 예시)

Convertio는 비교적 단순한 API 구조를 사용합니다:

POST https://api.convertio.co/convert
Content-Type: application/json

{
  "apikey": "YOUR_API_KEY",
  "input": "upload",
  "file": "<base64 encoded data>",
  "outputformat": "mp3"
}

또는 presigned upload URL을 받아서 multipart/form-data로 전송하는 방식도 지원합니다.

응답 예시:

{
  "data": {
    "id": "abcd1234",
    "status": "ok",
    "step": "convert"
  }
}

변환 완료 후:

GET https://api.convertio.co/convert/abcd1234/status

다운로드 URL:

{
  "data": {
    "output": {
      "url": "https://s3.convertio.co/download/abcd1234/file.mp3"
    }
  }
}

🔹 7. 정우님이 직접 만든다면 (파일 변환 서비스 API 설계 예시)

정우님이 직접 REST API 서버를 만든다면 다음처럼 설계할 수 있습니다:

단계	엔드포인트	설명
POST `/api/v1/convert`	변환 요청 생성 (파일명, 입력/출력 포맷 등록)
PUT `/api/v1/upload/:id`	presigned URL 발급 또는 직접 업로드
GET `/api/v1/convert/:id/status`	변환 진행 상태 확인
GET `/api/v1/convert/:id/download`	결과 다운로드

✅ 요약

구분	Convertio	CloudConvert	공통점
인증	API Key	Bearer Token	모두 필요
업로드 방식	Base64 or Form	Presigned URL	모두 REST 기반
변환 구조	단일 요청	태스크 기반 파이프라인	동일: 요청 → 업로드 → 변환 → 다운로드
상태 확인	`/status`	`/jobs/:id`	동일: polling 기반