ZIP 非同步匯入
專為 Obsidian 與 Markdown 套件匯出(含相對圖片引用)所設計,並透過任務佇列穩定處理匯入。
任務完成後回傳結果
建立任務並輪詢狀態後,即可取得可直接預覽、發布或交付後續流程的 HTML,無需額外手動清理。
主題感知渲染
確保品牌內容、知識庫發布與批次工作流程中的輸出樣式保持一致。
自動化資源管理
文章與資源保持整潔有序,讓搜尋、重複使用與團隊協作更易於管理。
典型使用案例
- 1
先將來自 Obsidian、知識庫或本地編輯檔案的 Markdown 文章打包成 ZIP 並上傳。
- 2
再建立非同步匯入任務,讓系統自動處理圖片上傳、引用路徑替換與版面轉換。
- 3
輪詢任務完成後,將產出的結果導入發布、分發、AI 增強或內部編輯流程中。
實際產出成果
- 在任務完成後回傳、適用於預覽、嵌入或後續發布的 HTML 內容
- 已清理圖片引用路徑的文章素材,方便進一步編輯
- 更穩定的資源結構,利於協作、歸檔與批次管理
- 來自不同來源的 Markdown 套件皆能保持一致的視覺輸出
API 金鑰與 AI 可讀文件
下方區塊同時作為開發者控制台與 AI / 工程團隊可直接使用的非同步整合文件。
ZIP 匯入 API 文件
一鍵建立 API 金鑰,並可直接複製下方 Markdown 指南給 AI 代理或工程團隊依照非同步流程接入。
建立匯入 API 金鑰
請登入以訪問此功能
現有金鑰
尚無 API 金鑰
主題 API 識別碼
每個 themeId 皆對應編輯器中顯示的主題名稱。人類可讀名稱與參考顏色列於下方。
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.linkhost, so clients only need one public base URL.
Authentication
Use an API key in the Authorization header:
Authorization: Bearer YOUR_API_KEY
Async workflow
- Upload the ZIP archive to the upload endpoint and get back
uploadRelativePath - Create an async import job with
POST https://api.imgto.link/api/v1/md/import - 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 1archiveFilename(required): original zip filenamearchiveSize(optional): archive size in bytesthemeId(optional): theme API name, default isclassicdirectoryPath(optional): base upload directory path likepublic/articles/launch-2026entryMarkdown(optional): specific markdown file path inside the ZIP when there are multiple markdown filessaveFolderId(optional): target markdown folder ID in the editormdfileId(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",
"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_COMPENSATIONandFAILED_COMPENSATION_ERROR resultis returned only when the job succeedserroris returned when the job fails
Result field notes
result.resolvedMarkdown: Markdown after local image paths are replaced with Imgto.link URLsresult.html: Base rendered HTML for preview or debuggingresult.wechatApiHtml: Recommended HTML for submitting to the WeChat Official Account APIcontentfieldresult.mdfileId: The saved Markdown article ID, returned for convenient reuse in the next replace import requestresult.savedArticle: Saved Markdown article record in the editorresult.savedArticle.mdfileId: Stable article identifier to pass back on the next import if you want to replace this article instead of creating a new oneresult.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
mdfileIdomitted: create a new import job using the uploaded ZIPmdfileIdprovided: 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
mdfileIdfrom 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.wechatApiHtmlfor WeChat Official Account API publishing - Do not use
result.htmlas thecontentfield if you need output aligned with the website's copy/export flow - Image URLs inside
result.wechatApiHtmlshould already point to uploaded Imgto.link assets - You still need to provide your own WeChat
access_tokenandthumb_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."