API Docs

BlogController API

Mikihands Blog Platform의 포스트 생성·수정·삭제를 API로 자동화할 수 있습니다. API 서버로 발생한 모든 요청은 안전하게 검증 후, 블로그에 반영 처리됩니다.
개발자가 아니더라도 사용자는 OpenAI의 MyGPT를 이용하여 손쉽게 포스팅 자동화를 구현할 수 있습니다.

Create Patch Delete Image Upload
← Back 무료로 시작하기 →
중요 안내
  • • API 기능은 유료사용자만 가능합니다.
  • • 본문(body)은 반드시 Markdown으로 작성되어야 합니다.
  • • 삭제/수정은 작성자(author)만 가능합니다. 반드시 자신의 Key로 호출해야하며 Key관리의 책임은 사용자에게 있습니다.
  • • 비정상적·악의적 사용(과도한 호출, 우회 시도 등)이 감지될 경우 서비스 보호를 위해 사전 통지 없이 이용이 제한될 수 있으며, 이 경우 남은 기간에 대한 환불은 제공되지 않습니다.

Base URL

https://api.mikihands.com

Authentication

이 API는 API Key 방식을 지원합니다. 키는 사용자 계정에 연결되어 있으며, 서버에서 Key를 이용하여 사용자를 식별하고 권한을 확인합니다.
API 요청기능은 유료구독자에게 제공되며, API Key는 블로그설정 메뉴에서 발급받을 수 있습니다.

API Key Header
Authorization: Api-Key <your_api_key>
or
X-API-KEY: <your_api_key>
서버는 Authorization: Api-Key ... 또는 X-API-KEY 둘 다 파싱합니다.
키 노출 정책
  • • API Key는 설정 화면에서 1회만 표시됩니다.
  • • 분실 시에는 “재발급(rotate)”을 통해 새 키를 발급하고, 기존 키는 폐기(revoke)합니다.
  • • POST/PATCH/DELETE는 작성자(author)만 가능하므로, 본인 키로 호출해야 합니다.

Endpoints

POST /api/blogcontroller/posts/
Create a post. 포스트를 신규로 발행합니다.
PATCH /api/blogcontroller/posts/{slug}/
Partial update. 발행된 포스트의 본문, 제목, meta description 등을 수정할 수 있습니다.
DELETE /api/blogcontroller/posts/{slug}/
Delete. 발생된 포스트를 삭제합니다. 삭제된 포스트는 복구할 수 없습니다.
POST /api/blogcontroller/image-upload/
이미지 업로드. 성공 시 image_url/image_id 반환

Images: Upload Workflow

TTL 30 minutes · Max 8 · WebP

보안을 위해 Mikihands API 서버는 사용자가 제공한 외부 URL을 직접 접근(다운로드)하지 않습니다. 이미지를 포함해 포스팅하려면 먼저 업로드 API로 이미지를 안전하게 등록한 뒤, 응답으로 받은 image_url / image_id를 사용하세요.

핵심 규칙
  • • 업로드 성공 시 image_url(본문에 삽입)과 image_id(포스팅 payload에 포함)를 받습니다.
  • • image_id는 30분 후 만료되며, 만료된 ID는 포스팅에 사용할 수 없습니다.
  • • 최대 8장, 파일 크기 5MB 이하, 해상도 2048×2048 이하.
  • • 지원 포맷은 PNG/JPEG/JPG/WebP 이며, 업로드된 이미지는 서버에서 WebP로 변환되어 저장됩니다.
  • • 이미지 업로드는 10r/1min 쓰로틀링의 제한이 있습니다.
Step 1) Upload image
POST /api/blogcontroller/image-upload/

이미지 파일을 multipart/form-data로 업로드합니다. 필드명은 file 입니다. 

curl -sS -X POST \
  "https://api.mikihands.com/api/blogcontroller/image-upload/" \
  -H "X-API-KEY: <your_api_key>" \
  -F "file=@/path/to/image.webp"
성공하면 아래와 같은 JSON을 반환합니다: 
{
  "success": true,
  "image_url": "/media/<username>/blog_img/<image_id>.webp",
  "image_id": "<image_id>"
}
Step 2) Use in Create / Patch
POST/PATCH /api/blogcontroller/posts/...

본문(body)에는 image_url을 그대로 Markdown 이미지 문법으로 삽입하고, 요청 payload에는 image_ids 배열에 image_id들을 포함하세요.

Body (Markdown) 예시
![cover](/media/<username>/blog_img/<image_id>.webp)

여기에 본문을 계속 작성...
Create/Patch payload에 포함할 값
{
  "image_ids": ["<image_id>", "<image_id2>"]
}
주의
  • • 이미지를 변경하는 PATCH는 보통 body도 함께 보내야 합니다.
  • • 만료된 image_id는 오류가 발생하므로, 업로드 후 30분 내에 포스팅 요청을 완료하세요.

Payload Examples

Create (새 포스트 생성)
POST /api/blogcontroller/posts/

{
  "title": "My first post",
  "slug": "my-first-post",
  "status": "PB",
  "categories": "Technology, AI",
  "tags": "mikihands, automation",
  "meta_description": "A concise meta description...",
  "body": "# Hello\\nThis is markdown."
}
CREATE 규칙
  • • 본문은 body에 Markdown 문자열로 전송합니다.
  • • 태그에 포함된 대문자는 서버에서 소문자로 변환됩니다.
  • • 이미지는 image-upload API로 업로드 후 반환되는 image_url + image_id를 사용하세요.
Create Payload Fields
* Required
Field Type Required Notes
title string Required 포스트 제목
slug string Required 영문 SEO용 슬러그 (중복 불가)
status string Required DF(Draft) / PB(Published)
categories string Required 쉼표로 구분된 카테고리 목록
tags string Optional 쉼표로 구분된 태그 목록
meta_description string Required SEO용 설명 (300자 제한)
body string Required Markdown 본문
image_ids string[] Optional 이미지 업로드 후 반환받은 ID (예:["0e809...", "0e884..."])
Patch (부분 수정)
PATCH /api/blogcontroller/{slug}/

{
  "lang_code": "ja",
  "primary_language": "en",
  "translation_languages": ["ja","fr","de","ko"],
  "title": "Updated title",
  "status": "PB",
  "categories": "Tech, AI",
  "tags": "django, automation",
  "meta_description": "Updated meta...",
  "body": "# Updated\nNew markdown content",
  "image_ids": ["0e809...", "0e884..."]
}
PATCH Payload Fields
* Required
Field Type Required Notes
lang_code string Required 수정 적용 언어 코드 (예: en, ja)
primary_language string Required 사용자 주 언어 (lang_code 검증용)
translation_languages string[] Required 사용자 번역 언어 목록 (lang_code 검증용)
title string Optional 포스트 제목
status string Optional DF(Draft) / PB(Published)
categories string Optional 쉼표로 구분 (예: "Tech","AI")
tags string Optional 쉼표로 구분 (예: "python","automation")
meta_description string Optional SEO 설명(권장 120~160자)
body string Optional Markdown 문자열. 서버가 HTML로 변환합니다.
image_ids string[] Optional 이미지 업로드 후 반환받은 ID (예:["0e809...", "0e884..."])
PATCH 필수 규칙
  • • lang_code는 반드시 primary_language 또는 translation_languages 안에 포함되어야 합니다.
  • • image_ids으로 이미지 변경을 요청할 때는 본문(body)을 함께 보내야 합니다.
  • • 응답은 202 Accepted가 될 수 있으며, 실제 반영은 약간의 지연이 있을 수 있습니다.
Delete
DELETE /api/blogcontroller/posts/{slug}/
DELETE 규칙
  • • 삭제는 작성자(author)만 가능합니다. (키에 매핑된 사용자 기준)
  • • 삭제된 포스트는 복구가 불가 합니다.

Common Errors

400 ValidationError
  • • slug 중복
  • • create에서 본문(body) 누락
  • • PATCH에서 lang_code / primary_language / translation_languages 누락
  • • img_name 수정인데 본문(body)이 함께 오지 않음
  • — Images —
  • • file 누락 (multipart 필드명 file)
  • • 지원하지 않는 이미지 포맷 (PNG/JPEG/WebP만 허용)
  • • 파일 크기 초과 (최대 5MB)
  • • 이미지 해상도 초과 (최대 2048×2048)
  • • 포스팅 요청에서 image_ids 최대 개수 초과 (최대 8개)
403 Forbidden
  • • 작성자(author) 불일치로 수정/삭제 불가
  • • 유료 구독자가 아님 (Not Paid Member)
410 Gone
  • • 만료된 image_id (TTL 30분)
  • • 만료된 image_id로 이미지 다운로드 또는 포스팅 시도
429 Too Many Requests
  • • 이미지 업로드 요청이 너무 잦음 (rate limit / throttle)
Tip
이미지 업로드 후 30분 내에 포스팅 요청을 완료하세요. 만료되면 새로 업로드해야 합니다.

Processing Notes

Mikihands Blog의 일부 기능은 처리에 시간(수 초에서 수십 초)이 걸릴 수 있습니다. 이는 AI가 실제로 연산을 수행하고 결과를 반영하는 과정이 포함되기 때문이며, 정상 동작입니다.

  • • 반영 지연 가능: 저장/수정 후 화면에 결과가 바로 보이지 않을 수 있어요. 잠시 후 새로고침하면 반영됩니다.
  • • 번역은 순차 처리: 여러 언어를 선택한 경우, 언어별로 생성되며 전체 완료까지 시간이 더 걸릴 수 있습니다.
  • • AI 결과는 검토 권장: AI는 문맥을 오해하거나 표현이 어색할 수 있습니다. 발행 전 미리보기에서 최종 확인을 권장합니다.
  • • 이미지/메타 정보: 자동 생성된 요소는 콘텐츠에 맞게 언제든 수정할 수 있습니다.
Tip
글을 발행한 뒤에도 부분 수정과 롤백이 가능하니, 처음부터 완벽하려고 부담 갖지 않아도 됩니다.
이제 자동화를 붙일 준비 끝.
랜딩으로 돌아가서 Developers 섹션에서 바로 연결해보세요.
Developers 섹션으로 →