API 사용법 — 처음 쓰는 분을 위한 안내
API라는 말을 몰라도 괜찮습니다. 이 기능은 챗GPT·클로드 같은 AI로 쓴 소설을 잉코라에 자동으로 올리는 창구입니다. 아래 순서대로만 따라 하면 됩니다.
· 쉬운 길 — AI가 만들어 준 글을 작가 스튜디오에 붙여넣기만 하면 끝 (코딩 필요 없음)
· 자는 길 — 프로그램(챗GPT·클로드·내가 만든 도구)이 자동으로 올리게 하려면 API 키가 필요합니다
1. API가 뭔가요?
API는 ‘창구’입니다. 사람이 홈페이지에 들어와서 손으로 회차를 올리는 대신, 다른 프로그램이 대신 올릴 수 있게 열어 둔 창구라고 생각하면 됩니다. 은행 창구에 가서 서류를 내면 직원이 처리하듯, 정해진 형식의 서류(JSON)를 창구에 내면 잉코라가 자동으로 접수합니다.
창구에 아무나 들어오면 안 되니 출입증이 필요한데, 그게 API 키입니다. 키는 비밀번호와 같습니다. 남에게 보여 주거나 인터넷에 올리면 안 됩니다.
그리고 창구를 통해 들어온 소설도 사람이 직접 올린 소설과 똑같이 검수를 거칩니다. AI로 쓴 작품이라는 사실도 함께 표시됩니다.
2. 준비물
- 잉코라 작가 계정 — 회원가입 후 작가 스튜디오를 열 수 있으면 됩니다. (독자와 작가는 같은 계정입니다)
- 올릴 소설 — 회차 본문은 한 화당 200자 이상이어야 합니다. (200자 미만은 접수되지 않습니다)
- (자는 길을 쓸 때만) API 키 1개 — 잉코라에서 무료로 발급합니다. 결제 없습니다.
3. 키 발급받기 (1분)
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_rating | general(전체) 또는 teen(14세 이상). 잉코라는 성인 등급을 운영하지 않습니다. |
| source_label | 어떤 AI로 썼는지 — 적지 않아도 됩니다(선택). 도구 이름을 요구하지 않습니다. |
| ai_tools | 쓰지 않습니다. 보내도 표기에는 쓰이지 않습니다. |
| episodes | 회차 목록. 1화 이상, 한 번에 최대 50화. 한 화 200자 ~ 60,000자, 전체 60만 자 이하. |
5. 쉬운 길 — 붙여넣기로 올리기 (코딩 없음)
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", ...}
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. 지켜야 할 것
- 내가 쓴(또는 내가 만든) 작품만 올립니다. 남의 작품을 그대로 올리면 저작권 침해로 삭제됩니다.
- AI 사용을 숨기지 않습니다. AI로 썼다는 표시만 하면 됩니다(도구 이름은 적지 않아도 됩니다). 잉코라는 AI 창작을 환영하는 곳입니다.
- 품질 없는 무더기 등록은 하지 않습니다. 같은 내용을 여러 작품으로 나눠 올리는 행위는 반려됩니다.
- 키는 나만 씁니다. 남에게 빌려 주거나 공유하지 않습니다.
- 성인(19금) 등급은 없습니다. 노골적인 성적 묘사·미성년 관련 내용은 접수되지 않습니다.
11. 쉬운 용어 사전
| 말 | 쉬운 뜻 |
|---|---|
| API | 프로그램끼리 서류를 주고받는 창구. |
| 엔드포인트(endpoint) | 창구의 주소. 예: /api/v1/open/works |
| API 키 | 창구에 들어갈 때 보여 주는 출입증(비밀번호). |
| Bearer | “이 키를 가진 사람의 요청입니다”라는 표시. 키 앞에 붙입니다. |
| JSON | 서류의 양식. { "이름": "값" } 모양으로 적습니다. |
| submission_id | 접수증 번호. 나중에 진행 상황을 물어볼 때 씁니다. |
| state(pending/approved/rejected) | 접수 상태: 검수 대기 / 등록됨 / 반려. |
막히면 물어보세요
이해가 안 되는 부분, 오류가 나는 부분은 고객센터 · AI 상담에 그대로 적어 주세요. 24시간 AI가 먼저 답하고, 사람 운영자가 이어서 확인합니다. 오류가 났다면 화면에 나온 문구를 그대로 붙여 주시면 빠릅니다.
작가 스튜디오 — API 발급 관리 열기 고객센터 · AI 상담