자유 이미지 생성 시작

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

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

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

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

{
  "prompt": "밤바다 위 불꽃놀이, 짙은 남색 하늘",
  "width": 1920,
  "height": 1080,
  "model": "gpt-image-2.5-flare"
}

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}'

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

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

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

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

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

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":"우상단에 로고"}]}'

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

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

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

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

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

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

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

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

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

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

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

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

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

발급된 키 목록 조회

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

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"

키 발급

업체 라벨을 지정해 새 키를 발급합니다. 응답에 평문 key 가 포함되며, 이후 목록 조회(GET)에서도 재조회할 수 있습니다. expiresInMonths 로 만료를 개월 단위로 걸 수 있습니다(선택, 생략 시 만료 없음). 발급 후 조정은 PATCH expiresAt.

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

키 수정 — 업체명(라벨)·한도(월/일)·만료일

발급된 키의 속성을 수정합니다. 본문의 hash/label 은 대상 키(셀렉터)이고, newLabel·quota·expiresAt 은 바꿀 값입니다 — 바꿀 값은 하나 이상 보냅니다. 업체명을 잘못 등록했으면 newLabel 로 고칩니다(2026-10-07부터). 키 값은 그대로라 업체의 API 호출에는 영향이 없고, 다른 활성 키(만료된 키 포함)와 같은 이름이면 409, 현재 이름과 같으면 변경 없이 200 입니다. 업체명을 바꿀 때는 대상을 hash 로 지정하세요. 생성 한도를 설정하거나(quota: { period, limit }) 해제하고(quota: null = 무제한), 만료일을 설정·연장·정정·해제합니다(expiresAt: "YYYY-MM-DD" KST 날짜 = 이 날부터 사용 불가, null = 만료 없음). 만료된 키는 폐기와 달리 레코드가 남아 있어 만료일을 미루면 즉시 다시 사용할 수 있습니다. 기간(monthly=KST 매월 1일 초기화 / daily=KST 자정 초기화)을 키마다 선택할 수 있습니다. 대상 키는 hash 또는 label(정확 일치) 중 하나로 지정합니다 — 라벨은 키와 1:1 이라 보통 label 만으로 충분하지만, 라벨은 바뀔 수 있으니 시스템에 저장해 두는 식별자는 hash 를 쓰세요. 한도는 키 레코드에만 저장되고 캐시가 없어 다음 생성 요청부터 즉시 반영됩니다 — 되돌리기는 이 API 1회로 끝나며 배포가 필요 없습니다. 한도가 소진되면 생성 요청이 429 QUOTA_EXCEEDED 로 거부됩니다. 소모는 성공 + 진행중 요청만 세고 실패한 요청은 세지 않습니다. period 를 monthly 로 설정하면 소진 시 Retry-After 가 이달 말까지 남은 초 — 최대 약 268만 초(31일)까지 커질 수 있으니, 고객사 연동 시 그 값 그대로 sleep-block 하지 말라고 안내하세요. 옛 dailyLimit 필드로 보내면 400 으로 거부됩니다 — quota: { period: "daily", limit } 로 바꿔 보내세요.

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

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

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

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

{
  "label": "초록우산",
  "expiresAt": "2026-08-12"
}

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

{
  "label": "초록우산",
  "expiresAt": "2026-01-01"
}

{
  "hash": "0b6f3625ca59f32f5f879b147d9f0ca71764924dd85720578fe6907b1248824f",
  "newLabel": "초록우산재단"
}

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}}'

키 폐기

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

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

키별 생성 내역 조회 (갤러리·추적용)

특정 키(사용 업체)가 free-images API 로 생성에 성공한 건을 반환합니다(실패·진행중은 포함하지 않음). 시스메이트가 업체별 갤러리를 만들거나 생성 내역을 추적하는 용도입니다. 재생성은 원본을 뿌리로 하는 스레드로 묶입니다: 항목의 rootId 가 스레드 id, regeneratedFrom 이 부모입니다. view=roots 로 스레드 뿌리만(변형 수·마지막 활동 시각 포함) 받고, rootId=<뿌리 id> 로 그 스레드 전체를 오래된 순으로 받습니다. 기간 제한 없이 전체가 대상이고 from/to 로 좁힐 수 있습니다. 각 항목은 요약이며 상세는 GET /v1/free-images/{id} 로 조회하세요. 썸네일(thumbnailUrl)은 2026-09-03 이후 생성분에 있으며 없으면 image.url(원본, 1~3MB)로 폴백해야 합니다. 이미지 URL 은 인증 없이 공개 서빙되므로 URL 을 아는 누구나 볼 수 있습니다(발급 키 응답과 동일).

curl -X GET "https://api.sysmate.example/api/admin/generations?label=%EC%B4%88%EB%A1%9D%EC%9A%B0%EC%82%B0&hash=:hash&view=:view&rootId=:rootId&from=:from&to=:to&limit=:limit&cursor=:cursor" \
  -H "x-admin-token: $API_TOKEN"

키별 사용량 조회

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

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"

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

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

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"

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

대상 키의 이번 기간(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 헤더가 필요합니다.

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

{
  "hash": "0b6f3625ca59f32f5f879b147d9f0ca71764924dd85720578fe6907b1248824f"
}

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":"초록우산"}'