콘텐츠 서버 API 규약
클라이언트 연동을 위한 HTTP 인터페이스입니다.
기본 정보
| Base URL | https://test-gj-qr.p-e.kr |
|---|---|
| 요청 형식 | multipart/form-data |
| 최대 파일 크기 | 20 MB |
| 지원 이미지 | JPEG, PNG, WebP |
| 인증 | 필수 — Authorization: Bearer <token> |
POST/api/v1/images
이미지와 콘텐츠 ID를 업로드하고 사용자가 접속할 이미지 페이지 URL을 발급합니다.
요청 필드
| 필드 | 형식 | 필수 | 설명 |
|---|---|---|---|
| image | File | 예 | JPEG, PNG 또는 WebP 이미지 |
| contentId | String | 예 | 활성화된 콘텐츠 ID |
사용 가능한 콘텐츠 ID
| ID | 콘텐츠 | 카테고리 |
|---|---|---|
BUDDHA_1 | 불상 따라하기 | 미륵 |
BUDDHA_2 | 불상 따라하기 | 사천왕 |
BUDDHA_3 | 불상 따라하기 | 금강역사상 |
BUDDHA_4 | 불상 따라하기 | 반가사유상 |
POTTERY_1 | 토기 만들기 | 집 모양 토기 |
POTTERY_2 | 토기 만들기 | 새 모양 토기 |
POTTERY_3 | 토기 만들기 | 삼채 뼈단지 |
POTTERY_4 | 토기 만들기 | 토우장식 항아리 |
성공 응답 · 201 Created
{
"imageId": "qfMzleoDlIr3",
"pageUrl": "https://test-gj-qr.p-e.kr/image/qfMzleoDlIr3",
"expiresAt": "2026-08-17T09:24:03.205Z"
}
expiresAt은 ISO 8601 UTC 형식입니다.
cURL 예제
curl -X POST "https://test-gj-qr.p-e.kr/api/v1/images" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-F "contentId=BUDDHA_1" \
-F "image=@sample.jpg"
사용자 처리 흐름
- 클라이언트가
POST /api/v1/images로 이미지를 업로드합니다. - 응답의
pageUrl을 QR 코드 또는 웹뷰에 사용합니다. - 사용자가 페이지에서 이름을 입력하고 이미지를 합성합니다.
- 결과 화면의 다운로드 버튼으로 JPEG 파일을 받습니다.
GET/api/v1/renders/{renderId}/download
합성된 JPEG 파일을 result.jpg라는 이름으로 다운로드합니다. renderId는 사용자 합성이 완료된 결과 페이지에서 생성됩니다.
GET/api/v1/renders/{renderId}/image
합성된 JPEG를 브라우저에서 바로 표시하는 URL입니다. <img src="..."> 또는 공유 링크에 사용할 수 있습니다.
오류 응답
| 상태 | 상황 | 응답 예시 |
|---|---|---|
| 400 | 파일 누락, 잘못된 콘텐츠 ID, 크기 초과 | { "error": "..." } |
| 401 | Bearer 토큰 누락 또는 불일치 | { "error": "유효한 Bearer 토큰이 필요합니다." } |
| 404 | 이미지·합성 파일이 없거나 만료됨 | 텍스트 오류 메시지 |
| 500 | 이미지 처리 또는 서버 내부 오류 | { "error": "..." } |
Unity C# 예제
using UnityEngine;
using UnityEngine.Networking;
using System.Collections;
IEnumerator UploadImage(byte[] imageBytes, string contentId)
{
var form = new WWWForm();
form.AddField("contentId", contentId);
form.AddBinaryData("image", imageBytes, "photo.jpg", "image/jpeg");
using var request = UnityWebRequest.Post("https://test-gj-qr.p-e.kr/api/v1/images", form);
request.SetRequestHeader("Authorization", "Bearer YOUR_API_TOKEN");
yield return request.SendWebRequest();
if (request.result == UnityWebRequest.Result.Success)
Debug.Log(request.downloadHandler.text);
else
Debug.LogError(request.downloadHandler.text);
}