{"id":23703315,"url":"https://github.com/saluana/markitdown-rest","last_synced_at":"2026-05-07T08:34:19.794Z","repository":{"id":268962628,"uuid":"905591229","full_name":"Saluana/markitdown-rest","owner":"Saluana","description":"A FastAPI service that converts documents to markdown and extracts YouTube transcripts, built on Microsoft's MarkItDown library.","archived":false,"fork":false,"pushed_at":"2024-12-20T00:38:44.000Z","size":35,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-20T05:17:40.358Z","etag":null,"topics":["fastapi","markdown","markdown-converter","rest-api"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Saluana.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-19T06:21:32.000Z","updated_at":"2025-01-21T07:02:46.000Z","dependencies_parsed_at":"2024-12-20T01:38:12.421Z","dependency_job_id":null,"html_url":"https://github.com/Saluana/markitdown-rest","commit_stats":null,"previous_names":["saluana/markitdown-rest"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Saluana%2Fmarkitdown-rest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Saluana%2Fmarkitdown-rest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Saluana%2Fmarkitdown-rest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Saluana%2Fmarkitdown-rest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Saluana","download_url":"https://codeload.github.com/Saluana/markitdown-rest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239780142,"owners_count":19695736,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","markdown","markdown-converter","rest-api"],"created_at":"2024-12-30T13:01:00.628Z","updated_at":"2026-01-31T04:30:16.052Z","avatar_url":"https://github.com/Saluana.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# File to Markdown API\n\nA FastAPI-based service built on top of Microsoft's MarkItDown library that provides endpoints for converting various document formats to markdown and extracting YouTube video transcripts.\nThis project extends MarkItDown's capabilities with additional features specifically focused on YouTube transcript extraction and web content conversion.\n\n## Features\n\n-   Convert various file formats to markdown\n-   Extract YouTube video transcripts with timestamps\n-   URL content conversion\n-   Support for multiple document formats including:\n    -   HTML\n    -   PDF\n    -   DOCX\n    -   XLSX\n    -   PPTX\n    -   Images\n    -   Audio files (WAV, MP3)\n    -   ZIP files\n    -   Wikipedia pages\n    -   YouTube pages / Videos\n\n## Installation\n\n1. Clone the repository\n2. Create a `.env` file with the following variables:\n\n```env\nPROXY_URL=your_proxy_url_if_needed\nOPENAI_API_KEY=your_openai_api_key\n```\n\n3. Build and run using Docker:\n\n```bash\ndocker build -t document-converter .\ndocker run -p 8000:8000 document-converter\n```\n\nOr install locally:\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\npip install -r requirements.txt\nuvicorn main:app --host 0.0.0.0 --port 8000\n```\n\n## API Endpoints\n\n### 1. Convert File\n\n```http\nPOST /convert/\nContent-Type: multipart/form-data\n\nfile: \u003cfile\u003e\n```\n\nConverts uploaded files to markdown format.\n\n### 2. Convert URL\n\n```http\nPOST /convert-url/\nContent-Type: application/x-www-form-urlencoded\n\nurl=https://example.com\n```\n\nConverts web page content to markdown format.\n\n### 3. YouTube Transcript\n\n```http\nPOST /youtube/\nContent-Type: application/x-www-form-urlencoded\n\nurl=https://www.youtube.com/watch?v=video_id\n```\n\nReturns:\n\n-   Full transcript without timestamps\n-   Timestamped transcript\n-   Markdown formatted transcript\n-   Structured transcript with timing information\n\n## Example Usage\n\n### Python\n\n```python\nimport requests\n\n# Convert URL\nresponse = requests.post(\n    \"http://localhost:8000/convert-url/\",\n    data={\"url\": \"https://example.com\"}\n)\nprint(response.json())\n\n# Get YouTube Transcript\nresponse = requests.post(\n    \"http://localhost:8000/youtube/\",\n    data={\"url\": \"https://www.youtube.com/watch?v=video_id\"}\n)\nprint(response.json())\n\n# Convert File\nwith open(\"document.pdf\", \"rb\") as f:\n    response = requests.post(\n        \"http://localhost:8000/convert/\",\n        files={\"file\": f}\n    )\nprint(response.json())\n```\n\n### cURL\n\n```bash\n# Convert URL\ncurl -X POST http://localhost:8000/convert-url/ \\\n  -H \"Content-Type: application/x-www-form-urlencoded\" \\\n  -d \"url=https://example.com\"\n\n# Get YouTube Transcript\ncurl -X POST http://localhost:8000/youtube/ \\\n  -H \"Content-Type: application/x-www-form-urlencoded\" \\\n  -d \"url=https://www.youtube.com/watch?v=video_id\"\n\n# Convert File\ncurl -X POST http://localhost:8000/convert/ \\\n  -F \"file=@document.pdf\"\n```\n\n## Dependencies\n\nThe project uses several key dependencies which are listed in the requirements.txt file:\n\n```1:18:requirements.txt\nfastapi[standard]\nuvicorn\npydub\nspeechrecognition\nyoutube-transcript-api\npython-dotenv\nopenai\npython-multipart\n# Add these missing dependencies:\nmammoth\nmarkdownify\npandas\npdfminer.six\npython-pptx\npuremagic\nrequests\nbeautifulsoup4\ncharset-normalizer\n```\n\n## Docker Configuration\n\nThe project includes a Dockerfile that sets up all necessary dependencies and environment:\n\n```1:54:Dockerfile\nFROM alpine:3.19\n\n# Set environment variables and locale\nENV PYTHONUNBUFFERED=1 \\\n    PYTHONDONTWRITEBYTECODE=1 \\\n    PATH=\"/app/.venv/bin:$PATH\" \\\n    LANG=C.UTF-8 \\\n    LC_ALL=C.UTF-8 \\\n    PYTHONIOENCODING=UTF-8\n\n# Install system dependencies and Python\nRUN apk add --no-cache \\\n    python3 \\\n    py3-pip \\\n    python3-dev \\\n    ffmpeg \\\n    exiftool \\\n    build-base \\\n    pango-dev \\\n    cairo-dev \\\n    jpeg-dev \\\n    zlib-dev \\\n    gcc \\\n    musl-dev \\\n    libffi-dev \\\n    git\n\nWORKDIR /app\n\n# Create and activate virtual environment\nRUN python3 -m venv .venv\n\n# Install dependencies with extras\nCOPY requirements.txt .\nRUN . .venv/bin/activate \u0026\u0026 \\\n    pip install --no-cache-dir -r requirements.txt \u0026\u0026 \\\n    pip install --no-cache-dir --upgrade \\\n    youtube-dl \\\n    youtube-transcript-api \\\n    pydub \\\n    speechrecognition \\\n    python-dotenv \\\n    openai \\\n    python-multipart\n\n# Copy application code\nCOPY . .\n\n# Expose the port\nEXPOSE 8000\n\n# Run using the full path to uvicorn\nCMD [\".venv/bin/uvicorn\", \"main:app\", \"--host\", \"0.0.0.0\", \"--port\", \"8000\"]\n\n```\n\n## Error Handling\n\nThe API includes comprehensive error handling and will return appropriate HTTP status codes and error messages when issues occur. All endpoints return JSON responses with either the requested data or detailed error information.\n\n## Notes\n\n-   For YouTube transcripts, the API attempts multiple methods to retrieve the transcript, including:\n    -   English only\n    -   Auto-generated captions\n    -   Multiple language variants\n    -   Available transcript list\n-   Proxy support is available through the PROXY_URL environment variable\n-   OpenAI integration is available for enhanced processing capabilities\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaluana%2Fmarkitdown-rest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsaluana%2Fmarkitdown-rest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaluana%2Fmarkitdown-rest/lists"}