Markdown2HTML API

將 Markdown ZIP 以非同步方式匯入為可投產的 HTML

上傳一個包含 Markdown 與本地圖片的 ZIP 壓縮檔,建立非同步匯入任務。系統會自動處理資源、修復引用路徑,並在任務完成後產出可供預覽、發布及後續工作流程使用的 HTML。

一次匯入文章與配圖

  • ZIP 匯入功能,無需手動上傳每一張圖片
  • 圖片會被自動處理並上傳,而 ZIP 本身不會儲存至 COS
  • 目錄路徑、主題樣式、已儲存文章與 AI 可讀文件整合於單一流程
Base URL: https://api.imgto.link

ZIP 非同步匯入

專為 Obsidian 與 Markdown 套件匯出(含相對圖片引用)所設計,並透過任務佇列穩定處理匯入。

任務完成後回傳結果

建立任務並輪詢狀態後,即可取得可直接預覽、發布或交付後續流程的 HTML,無需額外手動清理。

主題感知渲染

確保品牌內容、知識庫發布與批次工作流程中的輸出樣式保持一致。

自動化資源管理

文章與資源保持整潔有序,讓搜尋、重複使用與團隊協作更易於管理。

典型使用案例

  1. 1

    先將來自 Obsidian、知識庫或本地編輯檔案的 Markdown 文章打包成 ZIP 並上傳。

  2. 2

    再建立非同步匯入任務,讓系統自動處理圖片上傳、引用路徑替換與版面轉換。

  3. 3

    輪詢任務完成後,將產出的結果導入發布、分發、AI 增強或內部編輯流程中。

實際產出成果

  • 在任務完成後回傳、適用於預覽、嵌入或後續發布的 HTML 內容
  • 已清理圖片引用路徑的文章素材,方便進一步編輯
  • 更穩定的資源結構,利於協作、歸檔與批次管理
  • 來自不同來源的 Markdown 套件皆能保持一致的視覺輸出

API 金鑰與 AI 可讀文件

下方區塊同時作為開發者控制台與 AI / 工程團隊可直接使用的非同步整合文件。

ZIP 匯入 API 文件

一鍵建立 API 金鑰,並可直接複製下方 Markdown 指南給 AI 代理或工程團隊依照非同步流程接入。

建立匯入 API 金鑰

請登入以訪問此功能

現有金鑰

尚無 API 金鑰

主題 API 識別碼

每個 themeId 皆對應編輯器中顯示的主題名稱。人類可讀名稱與參考顏色列於下方。

預設主題
themeId: warm
系統預設
經典·溫暖
#ea580c
#333
中國風
themeId: china
思源宋體
古典·雅緻
#7f1d1d
#292524
#f5f5f4
賽博朋克
themeId: cyber
等寬字體
未來·霓虹·科技
#ec4899
#a855f7
#3b82f6
微信經典
themeId: classic
黑體 (Sans)
乾淨、安全、通用
#07c160
#333
墨染宋體
themeId: ink
宋體 (Serif)
文化、歷史、傳統
#3f3f46
#78716c
雜誌排版
themeId: editorial
襯線+黑體
時尚、藝術、高級灰
#1f2937
#ef4444
治癒文楷
themeId: wenkai
霞鶩文楷
情感、生活、手寫感
#57534e
#78716c
深度閱讀
themeId: business
系統黑體
商業、科技、乾貨
#1e3a8a
#1e40af
綠野仙蹤
themeId: forest
黑體 (Sans)
自然、旅行、清新
#059669
#ecfdf5
蔚藍海岸
themeId: azure
黑體 (Sans)
科技、夏日、通透
#0ea5e9
#e0f2fe
醇香咖啡
themeId: coffee
宋體 (Serif)
復古、故事、溫暖
#78350f
#fffbeb
賽博霓虹
themeId: neon
等寬 (Mono)
極客、前沿、潮流
#d946ef
#06b6d4
東方紅韻
themeId: red
宋體 (Serif)
國潮、節日、典雅
#be123c
#fff1f2
極客銀灰
themeId: silver
黑體 (Sans)
理性、冷淡、專業
#475569
#e2e8f0
極簡留白
themeId: minimal
無襯線
攝影、設計、冷淡
#000
#999
莫蘭迪粉
themeId: morandi
思源宋體
美妝、女性、溫柔
#be185d
#fbcfe8
暖陽活力
themeId: sunny
快樂體
美食、探店、年輕
#f97316
#fbbf24
薄荷夏日
themeId: mint
圓體 (Sans)
清涼、生活、治癒
#10b981
#d1fae5
金秋拾光
themeId: autumn
宋體 (Serif)
溫暖、故事、情感
#d97706
#fef3c7
普羅旺斯
themeId: lavender
宋體 (Serif)
夢幻、浪漫、唯美
#8b5cf6
#ede9fe
膠片電影
themeId: vintage
黑體 (Sans)
復古、暗調、影評
#7f1d1d
#fecaca
讀書筆記
themeId: notes
霞鶩文楷
高亮、手寫、乾貨
#facc15
#fef08a
高級煙灰
themeId: grey
黑體 (Sans)
極簡、冷淡、質感
#374151
#f3f4f6

AI 可讀的 API 整合指南

Imgto.link Markdown ZIP Import API

What this API does

  • Upload one ZIP package containing one Markdown file and its local images
  • Queue an asynchronous import job
  • Automatically create the target image directory if it does not exist
  • Automatically save the imported Markdown into the article folder 公众号
  • Upload referenced images to Imgto.link storage
  • Replace local image references in Markdown
  • Return the final resolved Markdown, HTML output, saved article info, and image directory path after the job completes

Base URL

https://api.imgto.link

Endpoints on the same host

  • ZIP upload endpoint: POST https://api.imgto.link/uploads/md-import
  • Create import job: POST https://api.imgto.link/api/v1/md/import
  • Poll job status: GET https://api.imgto.link/api/v1/md/import/jobs/{jobId}
  • In production you can proxy the control-plane routes on the same https://api.imgto.link host, so clients only need one public base URL.

Authentication

Use an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Async workflow

  1. Upload the ZIP archive to the upload endpoint and get back uploadRelativePath
  2. Create an async import job with POST https://api.imgto.link/api/v1/md/import
  3. Poll GET https://api.imgto.link/api/v1/md/import/jobs/{jobId} until the job reaches a terminal status

Step 1: upload ZIP archive

Endpoint

POST https://api.imgto.link/uploads/md-import

Content-Type

multipart/form-data

Form fields

  • archive (required): ZIP file containing one Markdown file and its local image files

Success response

{
  "code": 200,
  "data": {
    "relativePath": "inbox/2026/03/12/uuid-article-package.zip",
    "originalFilename": "article-package.zip",
    "size": 345678,
    "uploadedAt": "2026-03-12T08:00:00.000Z"
  }
}

Step 2: create import job

Endpoint

POST https://api.imgto.link/api/v1/md/import

Content-Type

application/json

Request body

{
  "uploadRelativePath": "inbox/2026/03/12/uuid-article-package.zip",
  "archiveFilename": "article-package.zip",
  "archiveSize": 345678,
  "themeId": "classic",
  "directoryPath": "public/articles/demo",
  "entryMarkdown": "docs/index.md",
  "saveFolderId": 12,
  "mdfileId": 123
}

Request field notes

  • uploadRelativePath (required): value returned from step 1
  • archiveFilename (required): original zip filename
  • archiveSize (optional): archive size in bytes
  • themeId (optional): theme API name, default is classic
  • directoryPath (optional): base upload directory path like public/articles/launch-2026
  • entryMarkdown (optional): specific markdown file path inside the ZIP when there are multiple markdown files
  • saveFolderId (optional): target markdown folder ID in the editor
  • mdfileId (optional): existing markdown article ID. When provided, the import is treated as a replace/update. The old article and its imported images are deleted before the new content is saved

Success response

{
  "code": 202,
  "message": "Accepted",
  "data": {
    "jobId": "mdi_1234567890abcdef",
    "status": "QUEUED",
    "progress": 0,
    "pollUrl": "/api/v1/md/import/jobs/mdi_1234567890abcdef"
  }
}

Step 3: poll job status

Endpoint

GET https://api.imgto.link/api/v1/md/import/jobs/{jobId}

Non-terminal response example

{
  "code": 200,
  "message": "Ok",
  "data": {
    "jobId": "mdi_1234567890abcdef",
    "status": "PROCESSING",
    "progress": 65,
    "currentStage": "processing_images",
    "message": "正在处理图片 2/4",
    "compensationStatus": "NOT_REQUIRED",
    "updatedAt": "2026-03-12T08:01:15.000Z"
  }
}

Completed response example

{
  "code": 200,
  "message": "Ok",
  "data": {
    "jobId": "mdi_1234567890abcdef",
    "status": "SUCCEEDED",
    "progress": 100,
    "currentStage": "completed",
    "message": "导入完成",
    "compensationStatus": "NOT_REQUIRED",
    "updatedAt": "2026-03-12T08:01:30.000Z",
    "result": {
      "mdfileId": 123,
      "resolvedMarkdown": "# Title\n\n![cover](https://...)",
      "html": "<section>...</section>",
      "wechatApiHtml": "<section>...</section>",
      "imageDirectoryPath": "public/公众号/my-article",
      "savedArticle": {
        "id": 123,
        "mdfileId": 123,
        "title": "My Article",
        "folder": {
          "id": 9,
          "name": "公众号",
          "fullPath": "公众号"
        }
      }
    }
  }
}

Failed response example

{
  "code": 200,
  "message": "Ok",
  "data": {
    "jobId": "mdi_1234567890abcdef",
    "status": "FAILED_COMPENSATED",
    "progress": 100,
    "currentStage": "failed",
    "message": "导入失败,已回滚上传图片与用户额度",
    "compensationStatus": "COMPLETED",
    "updatedAt": "2026-03-12T08:02:00.000Z",
    "error": {
      "message": "Referenced image not found: ./images/cover.png"
    }
  }
}

Job status notes

  • Terminal success status: SUCCEEDED
  • Terminal failure status: FAILED_COMPENSATED
  • Transitional failure statuses can appear briefly during rollback, such as FAILED_PENDING_COMPENSATION and FAILED_COMPENSATION_ERROR
  • result is returned only when the job succeeds
  • error is returned when the job fails

Result field notes

  • result.resolvedMarkdown: Markdown after local image paths are replaced with Imgto.link URLs
  • result.html: Base rendered HTML for preview or debugging
  • result.wechatApiHtml: Recommended HTML for submitting to the WeChat Official Account API content field
  • result.mdfileId: The saved Markdown article ID, returned for convenient reuse in the next replace import request
  • result.savedArticle: Saved Markdown article record in the editor
  • result.savedArticle.mdfileId: Stable article identifier to pass back on the next import if you want to replace this article instead of creating a new one
  • result.imageDirectoryPath: Final image upload directory path

Example cURL: step 1 upload

curl -X POST "https://api.imgto.link/uploads/md-import" \
  -F "archive=@article-package.zip" \

Example cURL: step 2 create job

curl -X POST "https://api.imgto.link/api/v1/md/import" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uploadRelativePath": "inbox/2026/03/12/uuid-article-package.zip",
    "archiveFilename": "article-package.zip",
    "archiveSize": 345678,
    "themeId": "classic",
    "directoryPath": "public/articles/demo"
  }'

Example cURL: step 3 poll job

curl -X GET "https://api.imgto.link/api/v1/md/import/jobs/mdi_1234567890abcdef" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example JavaScript: end-to-end async import

const uploadFormData = new FormData();
uploadFormData.append("archive", zipFile);

const uploadResponse = await fetch("https://api.imgto.link/uploads/md-import", {
  method: "POST",
  body: uploadFormData
});

const uploadResult = await uploadResponse.json();
const relativePath = uploadResult.data.relativePath;

const createResponse = await fetch("https://api.imgto.link/api/v1/md/import", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    uploadRelativePath: relativePath,
    archiveFilename: uploadResult.data.originalFilename,
    archiveSize: uploadResult.data.size,
    themeId: "classic",
    directoryPath: "public/articles/demo"
  })
});

const createResult = await createResponse.json();
const jobId = createResult.data.jobId;

let finalResult = null;

for (;;) {
  const pollResponse = await fetch("https://api.imgto.link/api/v1/md/import/jobs/" + jobId, {
    method: "GET",
    headers: {
      Authorization: "Bearer YOUR_API_KEY"
    }
  });

  const pollResult = await pollResponse.json();
  const job = pollResult.data;

  if (job.status === "SUCCEEDED") {
    finalResult = job.result;
    break;
  }

  if (job.status === "FAILED_COMPENSATED") {
    throw new Error(job.error?.message || "Import failed");
  }

  await new Promise((resolve) => setTimeout(resolve, 1800));
}

console.log(finalResult.mdfileId);
console.log(finalResult.resolvedMarkdown);
console.log(finalResult.wechatApiHtml);
console.log(finalResult.savedArticle);

Example: replace an existing imported article

Use the result.savedArticle.mdfileId returned by the previous successful import job.

const replaceResponse = await fetch("https://api.imgto.link/api/v1/md/import", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    uploadRelativePath: uploadedZip.data.relativePath,
    archiveFilename: uploadedZip.data.originalFilename,
    archiveSize: uploadedZip.data.size,
    themeId: "classic",
    mdfileId: previousResult.savedArticle.mdfileId
  })
});

const replaceResult = await replaceResponse.json();
console.log(replaceResult.data.jobId);

Replace behavior

  • mdfileId omitted: create a new import job using the uploaded ZIP
  • mdfileId provided: force this import to replace that exact article
  • During replacement, the job deletes the old markdown record first
  • It also deletes images previously imported for that markdown article before uploading the new images
  • Read the latest mdfileId from the final successful poll result and keep using it for future updates

Example: publish to WeChat Official Account draft API

Use result.wechatApiHtml from the completed import job for the content field instead of result.html.

const completedImport = await waitForImportJob(jobId);
const wechatApiHtml = completedImport.result.wechatApiHtml;

const draftPayload = {
  articles: [
    {
      title: completedImport.result.savedArticle?.title || "Imported article",
      author: "Your Team",
      digest: "",
      content: wechatApiHtml,
      content_source_url: "",
      thumb_media_id: "YOUR_WECHAT_THUMB_MEDIA_ID",
      need_open_comment: 0,
      only_fans_can_comment: 0
    }
  ]
};

const wechatResponse = await fetch(
  "https://api.weixin.qq.com/cgi-bin/draft/add?access_token=YOUR_WECHAT_ACCESS_TOKEN",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify(draftPayload)
  }
);

const wechatResult = await wechatResponse.json();
console.log(wechatResult);

WeChat publishing note

  • Prefer result.wechatApiHtml for WeChat Official Account API publishing
  • Do not use result.html as the content field if you need output aligned with the website's copy/export flow
  • Image URLs inside result.wechatApiHtml should already point to uploaded Imgto.link assets
  • You still need to provide your own WeChat access_token and thumb_media_id

Theme API names

  • 預設主題 (warm): #ea580c, #333
  • 中國風 (china): #7f1d1d, #292524, #f5f5f4
  • 賽博朋克 (cyber): #ec4899, #a855f7, #3b82f6
  • 微信經典 (classic): #07c160, #333
  • 墨染宋體 (ink): #3f3f46, #78716c
  • 雜誌排版 (editorial): #1f2937, #ef4444
  • 治癒文楷 (wenkai): #57534e, #78716c
  • 深度閱讀 (business): #1e3a8a, #1e40af
  • 綠野仙蹤 (forest): #059669, #ecfdf5
  • 蔚藍海岸 (azure): #0ea5e9, #e0f2fe
  • 醇香咖啡 (coffee): #78350f, #fffbeb
  • 賽博霓虹 (neon): #d946ef, #06b6d4
  • 東方紅韻 (red): #be123c, #fff1f2
  • 極客銀灰 (silver): #475569, #e2e8f0
  • 極簡留白 (minimal): #000, #999
  • 莫蘭迪粉 (morandi): #be185d, #fbcfe8
  • 暖陽活力 (sunny): #f97316, #fbbf24
  • 薄荷夏日 (mint): #10b981, #d1fae5
  • 金秋拾光 (autumn): #d97706, #fef3c7
  • 普羅旺斯 (lavender): #8b5cf6, #ede9fe
  • 膠片電影 (vintage): #7f1d1d, #fecaca
  • 讀書筆記 (notes): #facc15, #fef08a
  • 高級煙灰 (grey): #374151, #f3f4f6

ZIP package rules

  • Include exactly one Markdown file, or pass entryMarkdown
  • Reference local images with relative paths such as ./images/a.png
  • Remote image URLs are kept as-is
  • The API converts static images to AVIF by default
  • The imported Markdown is automatically saved to the article folder 公众号
  • The image upload directory becomes {directoryPath}/{article-slug}

AI integration instruction

If you give this API to an AI coding assistant, tell it:

"Use the async workflow. First upload the ZIP to https://api.imgto.link/uploads/md-import with multipart/form-data and read data.relativePath, data.originalFilename, and data.size. Then call POST https://api.imgto.link/api/v1/md/import with JSON using uploadRelativePath, archiveFilename, and optional themeId, directoryPath, entryMarkdown, saveFolderId, and mdfileId. Authenticate the control-plane API with Authorization: Bearer YOUR_API_KEY. Then poll GET https://api.imgto.link/api/v1/md/import/jobs/{jobId} until status becomes SUCCEEDED or FAILED_COMPENSATED. On success, read result.resolvedMarkdown, result.wechatApiHtml, result.savedArticle, result.mdfileId, and result.imageDirectoryPath. Prefer result.wechatApiHtml when publishing to the WeChat Official Account API content field."

檢視原始 Markdown