Markdown2HTML API

Turn Markdown ZIP packages into production-ready HTML with async import

Upload one ZIP archive with Markdown and local images, create an async import job, and get back HTML once processing finishes. The system handles assets, fixes references, and prepares output for preview, distribution, and downstream workflows.

Import an article and its images together

  • ZIP import without manually uploading every image
  • Images are processed and uploaded, while the ZIP itself never goes to COS
  • Directory paths, theme styles, saved articles, and AI-readable docs in one flow
Base URL: https://api.imgto.link

Async ZIP ingestion

Designed for Obsidian and Markdown package exports with relative image references and queue-based processing.

Final output after job completion

Create a job, poll its status, and receive HTML you can preview, publish, or hand off downstream without extra manual cleanup.

Theme-aware rendering

Keep output styling consistent across brand content, knowledge base publishing, and batch workflows.

Auto-organized assets

Articles and assets stay neatly organized so search, reuse, and team collaboration remain manageable.

Typical use cases

  1. 1

    Package Markdown articles from Obsidian, a knowledge base, or local editorial files into a ZIP archive and upload it first.

  2. 2

    Create an async import job so the system can handle image uploads, reference replacement, and layout conversion automatically.

  3. 3

    Poll until the job finishes, then feed the generated result into publishing, distribution, AI enrichment, or internal editing pipelines.

What you get in practice

  • HTML content returned after job completion, ready for preview, embedding, or downstream publishing
  • Article material with image references already cleaned up for further editing
  • A more stable asset structure for collaboration, archiving, and batch management
  • Consistent visual output across Markdown packages from different sources

API keys and AI-readable docs

The section below works as both a developer console and a copy-ready async integration handoff for AI or engineering teams.

ZIP import API docs

Create an API key in one click, then copy the Markdown guide below for your AI agent or engineering teammate to implement the async workflow.

Create import API key

Please login to access this feature

Existing keys

No API keys yet

Theme API identifiers

Each themeId matches the theme name shown in the editor. Human-readable names and reference colors are listed below.

Default Theme
themeId: warm
System Default
Classic, Warm
#ea580c
#333
Chinese Style
themeId: china
Noto Serif
Classical, Elegant
#7f1d1d
#292524
#f5f5f4
Cyberpunk
themeId: cyber
Monospace
Future, Neon, Tech
#ec4899
#a855f7
#3b82f6
WeChat Classic
themeId: classic
Sans
Clean, safe, versatile
#07c160
#333
Ink Serif
themeId: ink
Song (Serif)
Culture, history, tradition
#3f3f46
#78716c
Editorial Magazine
themeId: editorial
Serif + Sans
Fashion, art, premium gray
#1f2937
#ef4444
Healing WenKai
themeId: wenkai
WenKai
Emotional, daily life, handwriting
#57534e
#78716c
Deep Reading
themeId: business
System Sans
Business, tech, how-to
#1e3a8a
#1e40af
Forest Trail
themeId: forest
Sans
Nature, travel, fresh
#059669
#ecfdf5
Azure Coast
themeId: azure
Sans
Techy, summer, airy
#0ea5e9
#e0f2fe
Cozy Coffee
themeId: coffee
Serif
Vintage, stories, warmth
#78350f
#fffbeb
Cyber Neon
themeId: neon
Mono
Geeky, futuristic, trendy
#d946ef
#06b6d4
Oriental Red
themeId: red
Serif
Guochao, festive, elegant
#be123c
#fff1f2
Silver Tech
themeId: silver
Sans
Rational, cool, professional
#475569
#e2e8f0
Minimal Blanc
themeId: minimal
Sans
Photography, design, calm
#000
#999
Morandi Pink
themeId: morandi
Serif
Beauty, feminine, gentle
#be185d
#fbcfe8
Sunny Vibes
themeId: sunny
Playful
Food, shop tours, youthful
#f97316
#fbbf24
Mint Summer
themeId: mint
Rounded Sans
Cooling, life, healing
#10b981
#d1fae5
Golden Autumn
themeId: autumn
Serif
Warmth, stories, feelings
#d97706
#fef3c7
Provence
themeId: lavender
Serif
Dreamy, romantic, aesthetic
#8b5cf6
#ede9fe
Vintage Film
themeId: vintage
Sans
Retro, moody, reviews
#7f1d1d
#fecaca
Study Notes
themeId: notes
WenKai
Highlights, handwriting, tips
#facc15
#fef08a
Smoky Grey
themeId: grey
Sans
Minimal, cool, textured
#374151
#f3f4f6

AI-readable API integration guide

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

  • Default Theme (warm): #ea580c, #333
  • Chinese Style (china): #7f1d1d, #292524, #f5f5f4
  • Cyberpunk (cyber): #ec4899, #a855f7, #3b82f6
  • WeChat Classic (classic): #07c160, #333
  • Ink Serif (ink): #3f3f46, #78716c
  • Editorial Magazine (editorial): #1f2937, #ef4444
  • Healing WenKai (wenkai): #57534e, #78716c
  • Deep Reading (business): #1e3a8a, #1e40af
  • Forest Trail (forest): #059669, #ecfdf5
  • Azure Coast (azure): #0ea5e9, #e0f2fe
  • Cozy Coffee (coffee): #78350f, #fffbeb
  • Cyber Neon (neon): #d946ef, #06b6d4
  • Oriental Red (red): #be123c, #fff1f2
  • Silver Tech (silver): #475569, #e2e8f0
  • Minimal Blanc (minimal): #000, #999
  • Morandi Pink (morandi): #be185d, #fbcfe8
  • Sunny Vibes (sunny): #f97316, #fbbf24
  • Mint Summer (mint): #10b981, #d1fae5
  • Golden Autumn (autumn): #d97706, #fef3c7
  • Provence (lavender): #8b5cf6, #ede9fe
  • Vintage Film (vintage): #7f1d1d, #fecaca
  • Study Notes (notes): #facc15, #fef08a
  • Smoky Grey (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."

View raw Markdown