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

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

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

1. API가 뭔가요?

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

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

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

2. 준비물

3. 키 발급받기 (1분)

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

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

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

{
  "title": "작품 제목 (필수, 150자 이하)",
  "synopsis": "한 줄 소개 (선택, 5,000자 이하)",
  "genre_code": "fantasy",
  "tags": ["무협", "성장"],
  "age_rating": "general",
  "episodes": [
    { "title": "1화 제목", "body": "1화 본문… (200자 이상)" },
    { "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쓰지 않습니다. 보내도 표기에는 쓰이지 않습니다.
episodes회차 목록. 1화 이상, 한 번에 최대 50화. 한 화 200자 ~ 60,000자, 전체 60만 자 이하.

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

1작가 스튜디오의 ‘API 발급 관리’ 칸에서 붙여넣기로 올리기를 찾습니다.
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": "본문 전체" } 로. 본문은 줄이지 말고 그대로 넣어 줘.
- 본문 한 화는 200자 이상이어야 한다.

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

받은 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화 본문을 200자 이상 넣습니다." }
    ]
  }'

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

{
  "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",
    "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"},
)
with urllib.request.urlopen(req, timeout=120) as r:
    print(json.loads(r.read().decode()))      # {"submission_id": "...", "state": "pending", ...}
회차 본문을 txt 파일로 두고 읽어 올리면 편합니다. 여러 화를 한 번에 보내도 되고, 같은 작품을 이어서 올릴 때는 회차를 나눠 보내면 됩니다(한 번에 50화까지).

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 “본문 200자 이상”200자 미만 회차가 섞였습니다.본문을 채우거나, 그 회차를 빼고 올립니다.
429 “시간당 등록 한도(60건)”한 시간에 60건 넘게 보냈습니다.잠시 뒤 다시 시도합니다. (한 건에 여러 회차를 담으면 건수를 아낍니다)
키가 안 보입니다키는 발급 순간에만 보입니다.목록에서 폐기 후 새로 발급합니다.

10. 지켜야 할 것

11. 쉬운 용어 사전

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

막히면 물어보세요

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

작가 스튜디오 — API 발급 관리 열기 고객센터 · AI 상담