API 와 MCP

프로그램과 AI 에이전트에서 OmniDesk 를 부릅니다. 325종 변환, 33가지 파일 작업, 회사 드라이브 전부 API 로.

키 하나면 화면에서 되는 일이 전부 API 로도 됩니다. 따로 만든 것이 아니라 같은 것을 다른 문으로 들어오는 것입니다. 팀 요금제부터, 제어판 → API 키에서 만듭니다.

Claude·Cursor 에서 쓰기 (MCP)

AI 에이전트에게 "이 파일을 PDF 로 바꿔" 라고 하면 실제로 바꾸게 하는 설정입니다. 아래를 MCP 설정 파일에 붙여 넣고 키를 채우세요. 에이전트는 convert_file · file_action · find_route · list_formats · list_actions 다섯 가지 도구를 갖게 됩니다.

{
  "mcpServers": {
    "omnidesk": {
      "command": "uvx",
      "args": ["omnidesk-mcp"],
      "env": { "OMNIDESK_API_KEY": "od_..." }
    }
  }
}

pypi.org/project/omnidesk-mcp · github.com/work517/omnidesk-mcp

REST 로 직접 부르기

모든 요청에 X-API-Key 헤더를 붙입니다. 변환은 두 단계입니다 — 올려서 작업을 만들고, 끝날 때까지 물어본 뒤 결과를 받습니다.

# 1. upload and convert
curl -X POST https://app.omnidesk.win/api/jobs/quick \
  -H "X-API-Key: od_..." \
  -F "[email protected]" -F "dst_fmt=pdf"
# → {"job": {"id": "…", "status": "queued", …}}

# 2. poll
curl https://app.omnidesk.win/api/jobs/JOB_ID -H "X-API-Key: od_..."
# → {"status": "done", "result_node_id": "…", "quality": {"changes": [...]}}

# 3. download
curl https://app.omnidesk.win/api/drive/NODE_ID/download -H "X-API-Key: od_..."
# → {"url": "https://…"}   then GET that url

import httpx, time

c = httpx.Client(base_url="https://app.omnidesk.win",
                 headers={"X-API-Key": "od_..."})

with open("report.docx", "rb") as f:
    job = c.post("/api/jobs/quick",
                 files={"file": f}, data={"dst_fmt": "pdf"}).json()["job"]

while job["status"] not in ("done", "failed"):
    time.sleep(2)
    job = c.get(f"/api/jobs/{job['id']}").json()

url = c.get(f"/api/drive/{job['result_node_id']}/download").json()["url"]
open("report.pdf", "wb").write(httpx.get(url).content)

for change in job.get("quality", {}).get("changes", []):
    print(change["level"], change["text"])

주요 엔드포인트

POST /api/jobs/quick	올려서 변환. dst_fmt 에 쉼표로 여러 형식
POST /api/jobs/action	파일 작업 (표 추출·가리기·OCR·자막…)
GET /api/jobs/{id}	작업 상태와 품질 원장
GET /api/catalog/routes?src=&dst=	변환 경로와 대안
GET /api/catalog/actions	파일 작업 목록과 옵션
POST /api/drive/upload	드라이브에 올리기
GET /api/drive/{id}/download	내려받기 주소
GET /api/drive/list	드라이브 목록

무엇이 달라졌는지

작업 응답의 quality.changes 에 변환이 무엇을 잃었는지 적혀 있습니다 — 투명이 사라졌는지, 소리가 빠졌는지, 폰트가 바뀌었는지. level 이 warn 인 항목은 받는 사람이 열어 보고 놀랄 일입니다.

한도와 요금

API 로 만든 변환도 요금제의 월 한도에서 차감됩니다. 키는 회사당 10개, 언제든 폐기할 수 있고 폐기하면 즉시 멈춥니다.