홈으로

Content Generation API

v1
키 관리

Free Image Generation

자연어 프롬프트로 이미지 PNG 한 장을 생성합니다. 참고 이미지(url|b64, 최대 16장) 입력, 완료 결과 재생성(POST /v1/free-images/{id}/regenerate), 시안 기반 생성(/v1/references 등록·검수 후 필드 교체)을 지원합니다. 크기 생략 시 3840×2160, 장변 ≤3840px, 비율 제한 없음(3:1 초과는 밴드 합성). 3:1 초과 비율은 참고 최대 15장. 와이드 비율로 전자현수막·배너도 생성합니다. 프롬프트는 기본으로 LLM 정제를 거칩니다(refine:false 로 옵트아웃).

POST/v1/free-images Auth Raw Spec

자유 이미지 생성 시작

비동기 — 202 즉시 반환 후 백그라운드 생성. 요청 본문은 application/json.

Parameters

이름위치타입필수설명
Idempotency-KeyheaderstringminLength: 1maxLength: 255—같은 키로 24h 내 재호출 시 첫 응답 리플레이. 다른 본문이면 409.

요청 본문 · application/json · 필수

promptstringminLength: 1maxLength: 2000

이미지 묘사 자연어 프롬프트. reference 지정 시 선택('추가 요청' 역할 — 조립된 프롬프트 뒤에 덧붙여짐, 미지정 시 조립 프롬프트만 사용).

widthintegerdefault: 3840min: 1

생략 시 3840. 비율 제한 없음 — 3:1 초과는 밴드 합성으로 생성(유효 단변 해상도 = 3840/비율). 장변 ≤3840px. reference 지정 시 1920 또는 3840 만 가능(프리셋 잠금, 기본 3840). 세로형(aspect<1) 시안은 산출 height 가 두 프리셋 모두에서 상한(3840px)을 넘으면 400(세로형 정식 지원 없음).

heightintegerdefault: 2160min: 1

생략 시 2160. reference 지정 시 지정 불가(시안 aspect 로 산출됨).

imagesarray<object>minItems: 1maxItems: 16

참고 이미지 (선택, 최대 16장). 제공 시 참고 이미지를 반영해 생성합니다. 3:1 초과 비율에서는 최대 15장(영역 가이드 1슬롯). reference 와 동시 지정 불가(시안 이미지가 참고 슬롯을 전담).

array<RefImageItem> 의 항목:

urlstring (uri)format: uri

https 공개 이미지 URL

b64string

base64 인코딩 이미지 (data URI prefix 허용)

descriptionstringmaxLength: 500

이 이미지를 결과에 어떻게 반영할지 설명 (선택)

refinebooleandefault: true

LLM 이 느슨한 입력을 최종 이미지 프롬프트로 정규화합니다(플레이그라운드와 동일). 직접 다듬은 프롬프트를 그대로 쓰려면 false. 정제 결과는 응답의 refinedPrompt 로 확인할 수 있습니다. 정제는 생성 전 LLM 호출 1회를 추가합니다(수 초). reference 지정 시 이 값은 무시됨(조립 프롬프트가 이미 최종형).

referenceFreeImageReferenceParam
idstringrequired

시안 id (빌트인 또는 본인이 등록한 것)

fieldsobject

필드 key → 새 글자. required 필드는 필수, 미기재 선택 필드는 시안 원본 글자가 그대로 유지됨

예시

표준 — 표준 비율 이미지

{
  "prompt": "햇살 좋은 봄날의 벚꽃 가득한 캠퍼스, 따뜻한 파스텔 톤",
  "width": 3840,
  "height": 2160
}

배너 — 와이드 배너·전자현수막 (8:1)

{
  "prompt": "봄 신입사원 환영 현수막, 밝은 파스텔 배경에 벚꽃 장식, 가운데 환영 문구가 들어갈 여백",
  "width": 3840,
  "height": 480
}

시안(reference) — 등록된 시안 기반 생성 — 필드만 교체

{
  "reference": {
    "id": "ref_01HXX0KZ8N5R7E2WV9MT3FQGPB",
    "fields": {
      "main": "영업2팀 가을 워크샵",
      "date": "2026.10.03 ~ 05"
    }
  },
  "prompt": "배경을 가을 단풍 느낌으로"
}

예제 요청 (cURL)

curl -X POST "https://api.sysmate.example/v1/free-images" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"햇살 좋은 봄날의 벚꽃 가득한 캠퍼스, 따뜻한 파스텔 톤","width":3840,"height":2160}'

Responses

상태본문설명
GET/v1/free-images/{id} Auth Raw Spec

자유 이미지 리소스 조회 (폴링)

Parameters

이름위치타입필수설명
idpathstring예—

예제 요청 (cURL)

curl -X GET "https://api.sysmate.example/v1/free-images/:id" \
  -H "Authorization: Bearer $API_KEY"

Responses

상태본문설명
404—NOT_FOUND
POST/v1/free-images/{id}/regenerate Auth Raw Spec

완료된 이미지를 기준으로 재생성

succeeded 리소스의 결과 이미지 + 원래 프롬프트를 유지한 채 수정 요청(instruction)을 반영해 새 이미지 리소스를 만듭니다 (202 → 기존 GET 폴링). 재생성 결과를 다시 재생성할 수 있습니다.

Parameters

이름위치타입필수설명
idpathstring예원본(succeeded) 리소스 id
Idempotency-KeyheaderstringminLength: 1maxLength: 255—같은 키로 24h 내 재호출 시 첫 응답 리플레이. 다른 본문이면 409.

요청 본문 · application/json · 필수

instructionstringrequiredminLength: 1maxLength: 1000

이전 결과에 대한 수정 요청

imagesarray<object>minItems: 1maxItems: 15

추가 참고 이미지 (원본 결과가 자동으로 1번째 참고가 되므로 최대 15장). 극단 비율 원본은 추가 최대 14장.

array<RefImageItem> 의 항목:

urlstring (uri)format: uri

https 공개 이미지 URL

b64string

base64 인코딩 이미지 (data URI prefix 허용)

descriptionstringmaxLength: 500

이 이미지를 결과에 어떻게 반영할지 설명 (선택)

refineboolean

LLM 프롬프트 정제 여부. 생략 시 원본 리소스의 설정을 상속합니다(크기 상속과 같은 규칙).

예시

{
  "instruction": "배경을 밤하늘로 바꾸고 조명을 따뜻하게",
  "images": [
    {
      "url": "https://cdn.example.com/logo.png",
      "description": "우상단에 로고"
    }
  ]
}

예제 요청 (cURL)

curl -X POST "https://api.sysmate.example/v1/free-images/:id/regenerate" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instruction":"배경을 밤하늘로 바꾸고 조명을 따뜻하게","images":[{"url":"https://cdn.example.com/logo.png","description":"우상단에 로고"}]}'

Responses

상태본문설명
GET/v1/references Auth Raw Spec

시안 목록 (빌트인 + 내가 등록한 것)

예제 요청 (cURL)

curl -X GET "https://api.sysmate.example/v1/references" \
  -H "Authorization: Bearer $API_KEY"

Responses

상태본문설명
POST/v1/references Auth Raw Spec

시안 등록 — AI 가 교체 가능 텍스트 필드를 비동기 검출

요청 본문 · application/json · 필수

imageobjectrequired

url 또는 b64 중 정확히 하나

urlstring (uri)format: uri

https 공개 이미지 URL

b64string

base64 인코딩 이미지 (PNG/JPEG, 4MB 이하)

namestringmaxLength: 100

예제 요청 (cURL)

curl -X POST "https://api.sysmate.example/v1/references" \
  -H "Authorization: Bearer $API_KEY"

Responses

상태본문설명
GET/v1/references/{id} Auth Raw Spec

시안 상세 (검출된 fields 포함)

Parameters

이름위치타입필수설명
idpathstring예—

예제 요청 (cURL)

curl -X GET "https://api.sysmate.example/v1/references/:id" \
  -H "Authorization: Bearer $API_KEY"

Responses

상태본문설명
PATCH/v1/references/{id} Auth Raw Spec

검출 결과 검수·수정 — fields 는 배열 전체 교체

Parameters

이름위치타입필수설명
idpathstring예—

요청 본문 · application/json · 필수

namestringmaxLength: 100
fieldsarray<object>minItems: 1maxItems: 20

배열 전체 교체(부분 병합 아님) — GET 으로 받은 배열을 고쳐 통째로 보낼 것

array<ReferenceField> 의 항목:

keystringrequiredpattern: ^[a-z][a-zA-Z0-9]{0,29}$

필드 식별자 (생성 요청 reference.fields 의 키)

labelstringrequiredmaxLength: 50

사람이 읽는 필드 이름 (예: 중앙 제목, 일시, 장소)

originalstringrequiredmaxLength: 200

시안 이미지 속 원본 글자 — 교체 대상. 이미지와 정확히 일치해야 함

requiredbooleanrequired

true 면 생성 시 반드시 값을 넣어야 함

valueTemplatestringmaxLength: 200

라벨-빈칸 슬롯용 — 입력이 {v} 에 끼워짐 (선택)

예제 요청 (cURL)

curl -X PATCH "https://api.sysmate.example/v1/references/:id" \
  -H "Authorization: Bearer $API_KEY"

Responses

상태본문설명
DELETE/v1/references/{id} Auth Raw Spec

시안 삭제 (내가 등록한 것만)

Parameters

이름위치타입필수설명
idpathstring예—

예제 요청 (cURL)

curl -X DELETE "https://api.sysmate.example/v1/references/:id" \
  -H "Authorization: Bearer $API_KEY"

Responses

상태본문설명
204—삭제됨

Authentication

Content Generation API 공통 인증(Bearer) 안내와 키 검증 엔드포인트. AI 생성 기능 진입 전에 GET /v1/auth/verify 로 보유한 키가 유효한지 확인할 수 있습니다 — 유효하면 200, 없거나 잘못됐거나 폐기된 키면 401 입니다. 키가 노출되지 않도록 서버 측에서 호출하세요.

GET/v1/auth/verify Auth Raw Spec

보유한 API 키가 유효한지 확인

요청에 실은 Bearer 키가 유효하면 200 과 키 메타데이터를, 키가 없거나 잘못됐거나 폐기됐으면 401 을 반환합니다. AI 생성 메뉴 진입 시 사전 점검 용도로 사용하세요 — 200 이면 그대로 진행하고, 401 이면 사용자에게 유효한 키 등록을 안내하면 됩니다.

예제 요청 (cURL)

curl -X GET "https://api.sysmate.example/v1/auth/verify" \
  -H "Authorization: Bearer $API_KEY"

Responses

상태본문설명

Key Management (운영자용)

업체별 API 키를 발급·조회·폐기하는 운영자 API. 고객 키(Bearer)가 아니라 관리 토큰 x-admin-token 으로 인증하며, 발급된 평문 키는 생성 응답에서 단 한 번만 반환됩니다.

GET/api/admin/keys Auth Raw Spec

발급된 키 목록 조회

전체 키의 메타데이터를 최신순으로 반환합니다. 2026-08-03 이후 발급분은 평문 key 를 포함해 재복사할 수 있습니다. ?label= 로 특정 라벨의 키만 조회할 수 있습니다(정확 일치) — 한도 조정 전에 hash 를 찾는 용도로 편리합니다.

Parameters

이름위치타입필수설명
labelquerystring—라벨 정확 일치 필터. 일치하는 키가 없으면 빈 배열이 아니라 404 — 오타를 '키 없음'으로 오독하지 않게 합니다.예: 초록우산

예제 요청 (cURL)

curl -X GET "https://api.sysmate.example/api/admin/keys?label=%EC%B4%88%EB%A1%9D%EC%9A%B0%EC%82%B0" \
  -H "x-admin-token: $API_TOKEN"

Responses

상태본문설명
POST/api/admin/keys Auth Raw Spec

키 발급

업체 라벨을 지정해 새 키를 발급합니다. 응답에 평문 key 가 포함되며, 이후 목록 조회(GET)에서도 재조회할 수 있습니다.

요청 본문 · application/json · 필수

labelstringrequired

고객사명 등 식별 라벨. 앞뒤 공백은 제거되며, 제거 후 빈 문자열이면 400. 라벨은 키와 1:1 — 이미 같은 라벨의 키가 있으면 409 로 거부됩니다(2026-08-20부터). 키 교체 시에는 구 키를 먼저 폐기하거나 새 라벨을 쓰세요.

예제 요청 (cURL)

curl -X POST "https://api.sysmate.example/api/admin/keys" \
  -H "x-admin-token: $API_TOKEN"

Responses

상태본문설명
PATCH/api/admin/keys Auth Raw Spec

키 한도 설정·해제 (월/일)

발급된 키의 생성 한도를 설정하거나(quota: { period, limit }) 해제합니다(quota: null = 무제한). 기간(monthly=KST 매월 1일 초기화 / daily=KST 자정 초기화)을 키마다 선택할 수 있습니다. 대상 키는 hash 또는 label(정확 일치) 중 하나로 지정합니다 — 라벨은 키와 1:1 이라 보통 label 만으로 충분합니다. 한도는 키 레코드에만 저장되고 캐시가 없어 다음 생성 요청부터 즉시 반영됩니다 — 되돌리기는 이 API 1회로 끝나며 배포가 필요 없습니다. 한도가 소진되면 생성 요청이 429 QUOTA_EXCEEDED 로 거부됩니다. 소모는 성공 + 진행중 요청만 세고 실패한 요청은 세지 않습니다. period 를 monthly 로 설정하면 소진 시 Retry-After 가 이달 말까지 남은 초 — 최대 약 268만 초(31일)까지 커질 수 있으니, 고객사 연동 시 그 값 그대로 sleep-block 하지 말라고 안내하세요. 옛 dailyLimit 필드로 보내면 400 으로 거부됩니다 — quota: { period: "daily", limit } 로 바꿔 보내세요.

요청 본문 · application/json · 필수

다음 중 하나:

object

object

예시

월 한도 100건(현재 표준) — KST 매월 1일 초기화

{
  "label": "초록우산",
  "quota": {
    "period": "monthly",
    "limit": 100
  }
}

일 한도로 되돌리기 — period 가 바뀌면 리셋 마커는 지워집니다

{
  "label": "초록우산",
  "quota": {
    "period": "daily",
    "limit": 10
  }
}

한도 해제(무제한) — quota 를 null 로 명시 — 누락은 400

{
  "label": "초록우산",
  "quota": null
}

해시로 지정

{
  "hash": "0b6f3625ca59f32f5f879b147d9f0ca71764924dd85720578fe6907b1248824f",
  "quota": {
    "period": "monthly",
    "limit": 100
  }
}

예제 요청 (cURL)

curl -X PATCH "https://api.sysmate.example/api/admin/keys" \
  -H "x-admin-token: $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"초록우산","quota":{"period":"monthly","limit":100}}'

Responses

상태본문설명
DELETE/api/admin/keys Auth Raw Spec

키 폐기

해시로 키를 폐기합니다. 폐기는 캐시 없이 즉시 반영되어 해당 키의 API 호출이 곧바로 401 이 됩니다.

Parameters

이름위치타입필수설명
hashquerystringpattern: ^[0-9a-f]{64}$예폐기할 키의 sha256 해시(hex 64자). 목록·발급 응답의 hash 값을 사용합니다.예: 91351e313ea08e68fd7b5ad39401e3aedb350845233567950aaa00d6214e95f0

예제 요청 (cURL)

curl -X DELETE "https://api.sysmate.example/api/admin/keys?hash=91351e313ea08e68fd7b5ad39401e3aedb350845233567950aaa00d6214e95f0" \
  -H "x-admin-token: $API_TOKEN"

Responses

상태본문설명
204—폐기됨 (본문 없음)
GET/api/admin/usage Auth Raw Spec

키별 사용량 조회

기간 내 생성 요청을 키별·일별·엔드포인트별로 집계해 반환합니다. 집계는 전체 이벤트 기준이고, events 상세만 최신순 500건 캡입니다. 사용량 로그는 요청 수락 시 기록되는 편의 계층입니다 — 로깅 실패가 생성을 막지 않으며, 기록 시작 전 데이터는 소급되지 않습니다.

Parameters

이름위치타입필수설명
fromquerystringpattern: ^\d{4}-\d{2}-\d{2}$—조회 시작일 YYYY-MM-DD (UTC). 기본값은 to−6일(최근 7일). from ≤ to 여야 합니다.예: 2026-07-29
toquerystringpattern: ^\d{4}-\d{2}-\d{2}$—조회 종료일 YYYY-MM-DD (UTC). 기본값은 오늘. 기간은 최대 31일입니다.예: 2026-08-04
keyquerystring—특정 키만 집계 — summary·keyOptions 응답의 keyHash(sha256 hex) 값을 사용합니다. keyOptions 는 필터와 무관하게 전체 키를 유지합니다.

예제 요청 (cURL)

curl -X GET "https://api.sysmate.example/api/admin/usage?from=2026-07-29&to=2026-08-04&key=:key" \
  -H "x-admin-token: $API_TOKEN"

Responses

상태본문설명
GET/api/admin/usage/quota Auth Raw Spec

키별 한도·잔여 조회 (기간별)

발급된 모든 키의 현재 기간 창(키의 period 에 따라 오늘 또는 이달, KST) 한도·소모·잔여를 한 번에 반환합니다. 소모는 성공 + 진행중이며 실패한 요청은 세지 않습니다(결과물이 나가지 않은 요청은 소모하지 않는다는 정책). 재생성(regenerate)은 결과물이 나가는 별도 생성이라 1회 소모합니다. 한도 게이트와 같은 키 레코드를 읽으므로 값이 항상 일치합니다.

Parameters

이름위치타입필수설명
hashquerystringpattern: ^[0-9a-f]{64}$—키 해시 단건 조회.
labelquerystring—라벨 정확 일치 조회. hash 와 함께 주면 hash 가 우선합니다.예: 초록우산

예제 요청 (cURL)

curl -X GET "https://api.sysmate.example/api/admin/usage/quota?hash=:hash&label=%EC%B4%88%EB%A1%9D%EC%9A%B0%EC%82%B0" \
  -H "x-admin-token: $API_TOKEN"

Responses

상태본문설명
POST/api/admin/usage/quota/reset Auth Raw Spec

이번 기간 한도 초기화(리셋)

대상 키의 이번 기간(daily 키는 오늘, monthly 키는 이달, KST) 사용량을 다시 채웁니다. 사용량 기록은 지우지 않고 리셋 시각(resetAt)을 키에 기록해 그 이전 소모를 제외합니다 — 사용량 리포트·CSV 수치는 그대로입니다. 다음 기간이 시작되면 리셋은 자동으로 효력을 잃어 원래 한도로 돌아갑니다(복구 요청 불필요). 같은 기간에 다시 호출하면 그 시각까지 다시 비워집니다. 한도가 없는(무제한) 키는 400. 언제 쓰나: 고객이 이번 달 한도를 다 썼는데 추가 사용을 허용해야 할 때 — 한도를 올렸다가 다음 달에 다시 내리는 2회 작업 대신 이 API 1회로 끝냅니다. 한도 자체를 바꾸려면 PATCH /api/admin/keys 를 쓰세요(그때 period 가 바뀌면 리셋 마커는 지워집니다). 권장 절차: ① GET /api/admin/usage/quota?label=… 로 used·remaining 확인 → ② 이 API 호출 → ③ 응답의 exemptedCount(이번 리셋으로 면제된 소모 수)·remaining 확인 → ④ 필요하면 GET /api/admin/audit 에서 key.quota.reset 기록 확인. 모든 호출에 x-admin-token 헤더가 필요합니다.

요청 본문 · application/json · 필수

다음 중 하나:

object

object

예시

라벨로 지정(권장) — 라벨은 키와 1:1 — 사람이 치는 경로

{
  "label": "초록우산"
}

해시로 지정 — 스크립트·자동화 경로. 목록/잔여 조회 응답의 hash 를 그대로

{
  "hash": "0b6f3625ca59f32f5f879b147d9f0ca71764924dd85720578fe6907b1248824f"
}

예제 요청 (cURL)

curl -X POST "https://api.sysmate.example/api/admin/usage/quota/reset" \
  -H "x-admin-token: $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"초록우산"}'

Responses

상태본문설명