API 사용법 — 처음 쓰는 분을 위한 안내

API라는 말을 몰라도 괜찮습니다. 이 기능은 챗GPT·클로드 같은 AI로 쓴 소설을 잉코라에 자동으로 올리는 창구입니다. 아래 순서대로만 따라 하면 됩니다.

먼저 알아 두면 쉬워집니다. 복잡한 길과 쉬운 길 두 가지가 있습니다.
· 쉬운 길 — AI가 만들어 준 글을 작가 스튜디오에 붙여넣기만 하면 끝 (코딩 필요 없음)
· 자는 길 — 프로그램(챗GPT·클로드·내가 만든 도구)이 자동으로 올리게 하려면 API 키가 필요합니다

1. API가 뭔가요?

API는 ‘창구’입니다. 사람이 홈페이지에 들어와서 손으로 회차를 올리는 대신, 다른 프로그램이 대신 올릴 수 있게 열어 둔 창구라고 생각하면 됩니다. 은행 창구에 가서 서류를 내면 직원이 처리하듯, 정해진 형식의 서류(JSON)를 창구에 내면 잉코라가 자동으로 접수합니다.

창구에 아무나 들어오면 안 되니 출입증이 필요한데, 그게 API 키입니다. 키는 비밀번호와 같습니다. 남에게 보여 주거나 인터넷에 올리면 안 됩니다.

그리고 창구를 통해 들어온 소설도 사람이 직접 올린 소설과 똑같이 검수를 거칩니다. AI로 쓴 작품이라는 사실도 함께 표시됩니다.

2. 준비물

3. 키 발급받기 (1분)

1로그인 후 작가 스튜디오로 이동 왼쪽 메뉴(☰)의 API 발급을 누르거나 주소창에 inkora.kr/apikeys.html 를 넣습니다.
2키 이름을 적고 [API 키 발급]을 누릅니다 이름은 “챗GPT용”, “내 컴퓨터”처럼 알아보기 쉬운 말이면 됩니다. 이름은 나중에 바꿀 수 없으니 용도별로 하나씩 만드는 편이 좋습니다.
3키를 즉시 복사해 안전한 곳에 저장합니다 키는 발급한 순간 딱 한 번만 보입니다. 창을 닫으면 다시 볼 수 없습니다. 잃어버리면 그 키를 폐기하고 새로 만들면 됩니다.
4안 쓰는 키는 [폐기]로 끊어 둡니다 쓸 수 있는 키는 최대 5개입니다. 키는 90일 뒤에 자동 만료되며, 시간당 60건까지 올릴 수 있습니다.
키는 비밀번호입니다. 채팅창·게시판·블로그에 그대로 올리지 마세요. 다른 사람이 키를 가지면 내 이름으로 작품을 올릴 수 있습니다. 실수로 노출했다면 API 발급 페이지에서 즉시 폐기하고 새로 발급받으세요.

4. 올릴 내용 만들기 — 서류(JSON) 형식

창구에 내는 서류는 아래 모양입니다. 이 형식만 지키면 나머지는 AI가 채워 줍니다.

{
  "title": "작품 제목 (필수, 150자 이하)",
  "synopsis": "한 줄 소개 (선택, 5,000자 이하)",
  "genre_code": "fantasy",
  "tags": ["무협", "성장"],
  "age_rating": "general",
  "cover_image": "data:image/png;base64,iVBORw0…  (대표이미지·선택)",
  "episodes": [
    { "title": "1화 제목", "body": "1화 본문… (4,500~5,000자)",
      "images": ["data:image/png;base64,iVBORw0…  (삽화·선택)"] },
    { "title": "2화 제목", "body": "2화 본문…" }
  ]
}
항목설명
title작품 제목. 필수입니다.
synopsis작품 소개. 없으면 빈 문자열(“”)로 두면 됩니다.
genre_code아래 6개 중 하나만: fantasy(판타지) · martial_arts(무협) · romance(로맨스) · mystery(미스터리) · science_fiction(SF) · other(기타)
tags검색에 쓰일 낱말 최대 20개. 없어도 됩니다.
age_ratinggeneral(전체) 또는 teen(14세 이상). 잉코라는 성인 등급을 운영하지 않습니다.
source_label어떤 AI로 썼는지 — 적지 않아도 됩니다(선택). 도구 이름을 요구하지 않습니다.
ai_tools쓰지 않습니다. 보내도 표기에는 쓰이지 않습니다.
cover_image대표이미지(표지) — 선택. data:image/png;base64,… 형식. 완성된 세로 3:4 이미지만 받습니다(900×1,200 권장). 서버가 자르거나 늘리지 않으므로 완성본을 그대로 보냅니다. 비율이 다르면 422로 접수되지 않습니다.
episodes회차 목록. 1화 이상, 한 번에 최대 50화. 한 화 4,500~5,000자.
episodes[].images본문 삽화 — 선택, 회차마다 최대 10장. 같은 data URL 형식. 본문 뒤에 붙고 화면에서는 가로 4:3으로 보입니다. 그림은 글자 수에 들어가지 않습니다.
그림 넣기(선택) — 표지는 완성된 세로 3:4 이미지만 받습니다(900×1,200px 권장). 서버가 표지를 자르거나 늘리지 않으므로, 완성본을 그대로 보내야 화면에서 잘리지 않습니다. 삽화는 가로 4:3 칸에 비율을 지켜 잘려 보입니다(1,200×900px 권장). PNG·JPG·WEBP, 한 장 5MB 이하, 가로·세로 4,096px 이하. 보내는 방법은 본문과 같은 data URL 한 줄입니다 — data:image/png;base64, 뒤에 파일을 base64로 적으면 됩니다. 그림을 붙이지 않아도 등록·검수는 그대로 진행됩니다.

5. 쉬운 길 — 붙여넣기로 올리기 (코딩 없음)

1API 발급 페이지의 ‘붙여넣기로 올리기’ 칸에서 붙여넣기로 올리기를 찾습니다.
2위 4장 형식의 글을 상자에 붙여넣고 [등록 요청]을 누릅니다. 준비된 파일(.json)이 있다면 파일을 골라 올려도 됩니다.
3‘내가 올린 것’ 목록에서 상태를 확인합니다. 접수되면 검수 대기로 표시되고, 그 아래에서 진행 상황을 볼 수 있습니다.
이 길은 API 키가 필요 없습니다. 잉코라에 로그인한 내 계정으로 접수되므로, 키를 만들기 전에 먼저 연습해 보기에도 좋습니다.

6. AI에게 부탁하는 법 (복사해서 쓰는 글)

아래 글을 그대로 복사해서 챗GPT·클로드에게 보낸 뒤, 소설 내용을 함께 주면 JSON 형식으로 정리해 줍니다.

너는 웹소설 등록 도우미다. 아래 내 소설을 잉코라(inkora.kr)에 올릴 수 있는 JSON 하나로 정리해 줘.
설명이나 인사말 없이 JSON 코드블록 하나만 출력해.

규칙:
- title: 작품 제목
- synopsis: 3줄 이내 소개
- genre_code: fantasy | martial_arts | romance | mystery | science_fiction | other 중 하나
- tags: 핵심 낱말 5개
- age_rating: "general"
- episodes: 각 회차를 { "title": "n화 제목", "body": "본문 전체" } 로. 본문은 줄이지 말고 그대로 넣어 줘.
- 본문 한 화는 4,500자 이상 5,000자 이하로 쓴다(5,000자가 기준).
- cover_image(표지)와 images(삽화)는 넣지 마. 그림은 내가 따로 넣는다.

내 소설:
(여기에 회차 제목과 본문을 붙여넣기)

받은 JSON을 5장의 붙여넣기 상자에 넣고 [등록 요청]을 누르면 끝입니다. 긴 소설은 50화씩 나눠 올리면 됩니다.

7. 자동 등록 — 프로그램이 대신 올리게 하기

내 도구나 AI가 사람 손 없이 올리게 하려면 발급받은 키를 씁니다.

7-1. 주소와 방식

하는 일주소
작품 올리기POST https://inkora.kr/api/v1/open/works
진행 상태 보기GET https://inkora.kr/api/v1/open/submissions/{submission_id}

키는 머리글(헤더)에 아래처럼 넣습니다. Bearer 는 “이 키를 가진 사람의 요청”이라는 표시입니다.

Authorization: Bearer 발급받은_키
Content-Type: application/json

7-2. 붙여넣기 한 번으로 올리기 (윈도우 PowerShell / 맥 터미널)

아래에서 발급받은_키 자리에 내 키를 넣고, 명령 창에 붙여넣으면 됩니다. (-d 뒤가 4장의 서류입니다)

curl -X POST https://inkora.kr/api/v1/open/works \
  -H "Authorization: Bearer 발급받은_키" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "내 첫 AI 소설",
    "genre_code": "fantasy",
      "age_rating": "general",
    "episodes": [
      { "title": "1화", "body": "여기에 1화 본문을 4,500~5,000자로 넣습니다." }
    ]
  }'

잘 되면 이렇게 돌아옵니다:

{
  "submission_id": "0f3c…",
  "state": "pending",
  "message": "검수 대기로 접수했습니다. 승인되면 작품으로 자동 등록됩니다."
}

7-3. 파이썬으로 올리기

파이썬이 설치돼 있다면 아래 파일을 upload.py 로 저장하고 실행하면 됩니다. (설치 없이 기본 기능만 씁니다)

import json, urllib.request

KEY = "발급받은_키"          # 내 키로 바꾸세요
API = "https://inkora.kr/api/v1/open/works"

data = {
    "title": "내 첫 AI 소설",
    "synopsis": "한 줄 소개",
    "genre_code": "fantasy",
      "age_rating": "general",
    # 그림을 넣으려면: data URL 로 (표지=완성된 세로 3:4, 삽화=가로 4:3)
    # "cover_image": "data:image/png;base64," + base64.b64encode(open("표지.png","rb").read()).decode(),
    "episodes": [
        {"title": "1화", "body": open("1화.txt", encoding="utf-8").read()},
        {"title": "2화", "body": open("2화.txt", encoding="utf-8").read()},
    ],
}

req = urllib.request.Request(
    API,
    data=json.dumps(data).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + KEY,
        "Content-Type": "application/json",
        # ★User-Agent 를 꼭 넣으세요 — 없으면 보안 프록시가 403(error code: 1010)으로 막습니다
        "User-Agent": "my-inkora-uploader/1.0",
    },
)
with urllib.request.urlopen(req, timeout=120) as r:
    print(json.loads(r.read().decode()))      # {"submission_id": "...", "state": "pending", ...}
회차 본문을 txt 파일로 두고 읽어 올리면 편합니다. 여러 화를 한 번에 보내도 됩니다(한 번에 50화까지). 이미 올린 작품에 회차를 이어서 올릴 때는 POST /api/v1/open/works/{work_id}/episodes 로 회차 한 편씩 보냅니다. 작품 id 는 GET /api/v1/open/works 로 확인합니다(내 작품 목록과 회차 수가 나옵니다).

8. 올린 뒤에는 어떻게 되나요?

단계무슨 일이 일어나나요상태 표시
1. 접수서류가 들어오면 바로 접수되고 AI 사전 심사가 돕니다(금지 표현·분량 확인).검수 대기
2. 운영자 확인사람이 한 번 더 봅니다. 고칠 점이 있으면 알려 드립니다.검수 중 / 수정 요청
3. 승인작품과 회차가 자동으로 만들어지고 공개됩니다.등록됨 (작품 링크 표시)
4. 반려규정에 어긋나면 반려됩니다. 사유가 함께 표시됩니다.반려

진행 상황은 작가 스튜디오 → API 발급 관리 → ‘내가 올린 것’에서 언제든 볼 수 있고, 자동 등록을 쓸 때는 7-1의 상태 주소로도 확인할 수 있습니다.

9. 자주 나오는 오류와 해결

증상뜻해결
401 “API 키가 필요합니다”키를 안 넣었습니다.머리글에 Authorization: Bearer 내키 를 넣었는지 확인합니다. (Bearer 뒤 한 칸 띄우기)
401 “쓸 수 없는 API 키입니다 / 기간이 지난 키”키를 폐기했거나 90일이 지났습니다.새 키를 발급받아 바꿔 넣습니다.
409 “쓸 수 있는 키는 5개까지입니다”키를 5개 넘게 만들었습니다.안 쓰는 키를 폐기한 뒤 새로 만듭니다.
422 “없는 장르 코드입니다”genre_code 철자가 다릅니다.4장의 6개 코드 중 하나를 정확히 씁니다(예: martial_arts).
422 “전체 분량이 너무 큽니다”한 번에 60만 자를 넘었습니다.회차를 나눠 여러 번 올립니다.
422 “본문 분량이 기준 밖입니다”4,500자 미만이거나 5,000자를 넘는 회차가 섞였습니다.4,500~5,000자로 맞춰 다시 올립니다.
422 “표지는 완성된 세로 3:4 이미지만 됩니다”표지 비율이 3:4 가 아닙니다(가로형·정사각형 등).900×1,200 세로 표지를 만들어 올리거나, 표지를 빼고 올립니다.
429 “시간당 등록 한도(60건)”한 시간에 60건 넘게 보냈습니다.잠시 뒤 다시 시도합니다. (한 건에 여러 회차를 담으면 건수를 아낍니다)
403 “error code: 1010”보안 프록시가 프로그램을 막았습니다(User-Agent 없음).요청 머리글에 User-Agent 를 넣습니다. 브라우저·curl 은 자동으로 붙습니다.
키가 안 보입니다키는 발급 순간에만 보입니다.목록에서 폐기 후 새로 발급합니다.

10. 지켜야 할 것

11. 쉬운 용어 사전

말쉬운 뜻
API프로그램끼리 서류를 주고받는 창구.
엔드포인트(endpoint)창구의 주소. 예: /api/v1/open/works
API 키창구에 들어갈 때 보여 주는 출입증(비밀번호).
Bearer“이 키를 가진 사람의 요청입니다”라는 표시. 키 앞에 붙입니다.
JSON서류의 양식. { "이름": "값" } 모양으로 적습니다.
submission_id접수증 번호. 나중에 진행 상황을 물어볼 때 씁니다.
state(pending/approved/rejected)접수 상태: 검수 대기 / 등록됨 / 반려.

막히면 물어보세요

이해가 안 되는 부분, 오류가 나는 부분은 고객센터에 그대로 적어 주세요. 24시간 AI가 먼저 답하고, 사람 운영자가 이어서 확인합니다. 오류가 났다면 화면에 나온 문구를 그대로 붙여 주시면 빠릅니다.

API 발급 페이지 열기 고객센터