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

• Tema por defecto (warm): #ea580c, #333
• Estilo Chino (china): #7f1d1d, #292524, #f5f5f4
• Cyberpunk (cyber): #ec4899, #a855f7, #3b82f6
• WeChat Clásico (classic): #07c160, #333
• Ink Serif (ink): #3f3f46, #78716c
• Revista Editorial (editorial): #1f2937, #ef4444
• Sanación WenKai (wenkai): #57534e, #78716c
• Lectura Profunda (business): #1e3a8a, #1e40af
• Sendero Forestal (forest): #059669, #ecfdf5
• Costa Azul (azure): #0ea5e9, #e0f2fe
• Café Acogedor (coffee): #78350f, #fffbeb
• Cyber Neón (neon): #d946ef, #06b6d4
• Rojo Oriental (red): #be123c, #fff1f2
• Plata Tech (silver): #475569, #e2e8f0
• Blanco Minimal (minimal): #000, #999
• Rosa Morandi (morandi): #be185d, #fbcfe8
• Vibras Soleadas (sunny): #f97316, #fbbf24
• Verano Menta (mint): #10b981, #d1fae5
• Otoño Dorado (autumn): #d97706, #fef3c7
• Provenza (lavender): #8b5cf6, #ede9fe
• Película Vintage (vintage): #7f1d1d, #fecaca
• Notas de Estudio (notes): #facc15, #fef08a
• Gris Ahumado (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."