엔드포인트
POST /v1/guard/{api-id}/analyze
Authorization: Bearer {api-key}
Content-Type: application/json
Top-Level 필드
| Field | Type | Required | 설명 |
|---|
messages | array | 필수 | OpenAI 포맷 메시지. 마지막 user 메시지가 분석 대상이며, 나머지는 컨텍스트. |
opticon | object | 선택 | Opticon 트레이싱 메타데이터. |
messages — Content 형식
content의 형태는 API에 바인딩된 InputType에 따라 달라집니다:
{
"role": "user",
"content": "이 텍스트를 분석해주세요."
}
{
"role": "user",
"content": [
{ "type": "text", "text": "이 이미지를 분석해주세요." },
{
"type": "image",
"image": {
"data": "/9j/4AAQ...",
"media_type": "image/jpeg"
}
}
]
}
{
"role": "user",
"content": [
{ "type": "text", "text": "이 문서를 분석해주세요." },
{
"type": "file",
"file": {
"data": "<base64_encoded_pdf>",
"filename": "report.pdf",
"media_type": "application/pdf"
}
}
]
}
각 Guard API는 하나의 InputType에만 바인딩됩니다. 타입이 다른 데이터를 전송하면 400 INVALID_INPUT_TYPE이 반환됩니다.
opticon — 트레이싱 메타데이터
모든 필드는 선택입니다.
| Field | Type | 설명 |
|---|
trace_id | string | 커스텀 Trace ID. 생략 시 서버가 UUID를 생성. |
session_id | string | 여러 요청을 하나의 세션으로 그룹핑. |
user_id | string | 최종 사용자 식별자. |
metadata | object | Trace에 기록할 자유형 key-value. |
tags | array[string] | 필터링용 태그. |
Credentials는 서버 내부에서 관리됩니다. Langfuse의 public/secret key는 opticon에 전달하지 않으며, Guardian Bastion이 서버 측에서 관리합니다. 클라이언트는 트레이싱 메타데이터만 제공합니다.
전체 예시
{
"messages": [
{ "role": "system", "content": "You are a helpful assistant." },
{ "role": "user", "content": "HBM4 로드맵을 알려줘." }
],
"opticon": {
"session_id": "fab-chat-session",
"user_id": "engineer-park",
"metadata": { "department": "semiconductor", "environment": "production" },
"tags": ["fab-analysis", "sensitive"]
}
}
