---
title: "채팅 API"
description: "채팅 완료 및 멀티턴 대화를 통해 마인드와 상호작용하세요."
---

# 채팅 API

마인드에 메시지를 보내고 AI가 생성한 응답을 받으세요. 채팅 API는 상태 비저장(stateless) 완료와 자동 기록 관리가 포함된 상태 저장(stateful) 멀티턴 대화를 모두 지원합니다.

## 상태 저장 채팅 (권장)

서버가 대화 기록, 컨텍스트 압축, 롤링 요약을 자동으로 관리하는 영구적인 대화를 생성합니다. 요청할 때마다 전체 메시지 기록을 보낼 필요가 없습니다.

### 채팅 생성

마인드에 연결된 새로운 상태 저장 대화를 생성합니다.

**엔드포인트:** `POST /api/v1/chats`

**헤더:**

```text
Authorization: Bearer minds_your_api_key
Content-Type: application/json
```

**요청 본문:**

```json
{
  "name": "My Conversation",
  "sparkId": "your-mind-id"
}
```

<table>
<thead>
  <tr>
    <th>
      파라미터
    </th>
    
    <th>
      타입
    </th>
    
    <th>
      필수
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      채팅 표시 이름 (기본값: "API 채팅")
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sparkId
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      채팅할 마인드. 생략 시 나중에 마인드를 할당할 수 있습니다.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      선택적 설명
    </td>
  </tr>
</tbody>
</table>

**응답 (201):**

```json
{
  "data": {
    "id": "601af953-3837-49c1-a31e-4fdbfa82ac04",
    "name": "My Conversation",
    "description": null,
    "createdAt": "2026-04-04T12:45:24.078Z",
    "sparks": [
      {
        "id": "4774888e-0a03-40d7-979b-39b47c4c049c",
        "name": "Ada Lovelace",
        "discipline": "mathematician and computer scientist"
      }
    ]
  }
}
```

### 메시지 보내기

기존 채팅에 메시지를 보냅니다. 서버가 대화 기록, 컨텍스트 창 압축, 롤링 요약을 자동으로 처리합니다.

**엔드포인트:** `POST /api/v1/chats/{chatId}/messages`

**헤더:**

```text
Authorization: Bearer minds_your_api_key
Content-Type: application/json
```

**요청 본문:**

```json
{
  "content": "What are the latest advancements in solar panel technology?"
}
```

<table>
<thead>
  <tr>
    <th>
      파라미터
    </th>
    
    <th>
      타입
    </th>
    
    <th>
      필수
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        content
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        예
      </strong>
    </td>
    
    <td>
      메시지 텍스트 (또는 <code>
        message
      </code>
      
       사용)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        model
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      이 메시지에 대한 AI 모델을 재정의합니다. <code>
        provider
      </code>
      
      와 함께 보내야 합니다.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        provider
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      모델 재정의를 위한 AI 제공자: <code>
        openai
      </code>
      
      , <code>
        anthropic
      </code>
      
       또는 <code>
        google
      </code>
      
      . <code>
        model
      </code>
      
      와 함께 보내야 합니다.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        endUserName
      </code>
    </td>
    
    <td>
      string|null
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      이 요청의 실제 최종 사용자를 위한 선택적 표시 이름입니다. 생략되거나 <code>
        null
      </code>
      
       또는 빈 값이면 Minds는 중립적으로 호칭하며 API 키 또는 계정 소유자에서 이름을 추론하지 않습니다. 별칭: <code>
        userDisplayName
      </code>
      
      , <code>
        userName
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

상태 저장 채팅 모델 선택은 다음 순서를 따릅니다: 요청별 재정의, 팀의 선호 제공자(설정 및 자격이 있는 경우), 제품 기본값. 이 엔드포인트에서는 부분 재정의가 `400 Bad Request`로 거부됩니다. `model`와 `provider`를 모두 보내거나 둘 다 생략해야 합니다.

**응답:**

```json
{
  "content": "Recent advancements in solar panel technology include perovskite cells with 30%+ efficiency...",
  "messageId": "cmnkbsddh00033v01ptk9t4et"
}
```

<table>
<thead>
  <tr>
    <th>
      필드
    </th>
    
    <th>
      타입
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        content
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      마인드의 응답
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        messageId
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      저장된 메시지의 고유 ID
    </td>
  </tr>
</tbody>
</table>

### 멀티턴 예시

상태 저장 채팅에서는 매번 새 메시지만 보내면 됩니다. 서버가 모든 것을 기억합니다:

```bash
# Step 1: Create a chat
CHAT=$(curl -s -X POST "https://getminds.ai/api/v1/chats" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Research Session", "sparkId": "your-mind-id" }')

CHAT_ID=$(echo $CHAT | jq -r '.data.id')

# Step 2: Send messages (server manages history automatically)
curl -X POST "https://getminds.ai/api/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "content": "What are the top marketing trends?" }'

# Step 3: Follow up (the mind remembers the previous exchange)
curl -X POST "https://getminds.ai/api/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Which of those would work best on a small budget?" }'
```

**내부 동작 방식:**

- 모든 메시지는 데이터베이스에 영구 저장됩니다
- 최근 8개 메시지는 전체 컨텍스트로 전송됩니다
- 오래된 메시지는 롤링 LLM 요약으로 압축됩니다
- 컨텍스트 제한에 도달하지 않고 몇 주 또는 몇 달 동안 대화를 이어갈 수 있습니다

---

## 상태 비저장 완료

단일 요청이나 대화 기록을 직접 관리하고 싶을 때 사용합니다.

### 메시지 보내기

마인드에 메시지를 보내고 응답을 받습니다.

**엔드포인트:** `POST /api/v1/minds/{mindId}/completion`

**헤더:**

```text
Authorization: Bearer minds_your_api_key
Content-Type: application/json
```

### 요청 본문

```json
{
  "messages": [
    {
      "role": "user",
      "content": "What are the latest advancements in solar panel technology?"
    }
  ]
}
```

### 파라미터

<table>
<thead>
  <tr>
    <th>
      파라미터
    </th>
    
    <th>
      타입
    </th>
    
    <th>
      필수
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        messages
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      메시지 객체 배열 (<code>
        user
      </code>
      
      , <code>
        assistant
      </code>
      
       또는 <code>
        tool
      </code>
      
      ). 필드를 완전히 생략하거나 빈 배열을 보내 인사말 부트스트랩을 트리거할 수 있습니다 (아래 <em>
        초기 메시지
      </em>
      
       참조).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        messages[].role
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        예
      </strong>
    </td>
    
    <td>
      <code>
        "user"
      </code>
      
      , <code>
        "assistant"
      </code>
      
       또는 <code>
        "tool"
      </code>
      
       중 하나
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        messages[].content
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        예
      </strong>
    </td>
    
    <td>
      메시지 텍스트. <code>
        user
      </code>
      
       메시지의 경우 비어 있지 않은 문자열이어야 합니다 (공백은 <code>
        400
      </code>
      
      로 거부됨). <code>
        tool
      </code>
      
       역할의 경우 생략하고 대신 <code>
        tool_call_id
      </code>
      
       + <code>
        content
      </code>
      
      를 사용하세요.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        model
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      이 요청에 사용되는 AI 모델을 재정의합니다. 아래 <a href="#model-override">
        모델 재정의
      </a>
      
      를 참조하세요.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        provider
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      모델 재정의를 위한 AI 제공자: <code>
        openai
      </code>
      
      , <code>
        anthropic
      </code>
      
       또는 <code>
        google
      </code>
      
      . 가능한 경우 모델 이름에서 자동 감지됩니다.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        endUserName
      </code>
    </td>
    
    <td>
      string|null
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      이 요청의 실제 최종 사용자를 위한 선택적 표시 이름입니다. 생략되거나 <code>
        null
      </code>
      
       또는 빈 값이면 Minds는 중립적으로 호칭하며 API 키 또는 계정 소유자에서 이름을 추론하지 않습니다. 별칭: <code>
        userDisplayName
      </code>
      
      , <code>
        userName
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        language
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      응답 언어 힌트. 지원 언어: <code>
        en
      </code>
      
      , <code>
        de
      </code>
      
      , <code>
        es
      </code>
      
      , <code>
        fr
      </code>
      
      , <code>
        zh
      </code>
      
      , <code>
        tr
      </code>
      
      , <code>
        ar
      </code>
      
      , <code>
        ja
      </code>
      
      , <code>
        ko
      </code>
      
      . 강력한 페르소나(예: 고정된 모국어를 가진 공인의 클론)는 페르소나의 언어로 계속 응답할 수 있습니다.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        generateImage
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      <code>
        true
      </code>
      
      일 때, 문맥에 적합한 경우 응답에 AI 이미지 생성을 활성화합니다
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        response_format
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      구조화된 출력을 요청합니다. 아래 <a href="#structured-output">
        구조화된 출력
      </a>
      
      을 참조하세요.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tools
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      사용자 정의 도구 정의 배열. 아래 <a href="#tool-calling">
        도구 호출
      </a>
      
      을 참조하세요.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tool_choice
      </code>
    </td>
    
    <td>
      string|object
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      도구 호출 동작을 제어합니다. <a href="#tool-choice-modes">
        도구 선택 모드
      </a>
      
      를 참조하세요.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parallel_tool_calls
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      턴당 여러 도구 호출을 허용합니다 (기본값: <code>
        true
      </code>
      
      ).
    </td>
  </tr>
</tbody>
</table>

### 응답

```json
{
  "messageId": "msg_550e840029b141d4a716446655440000",
  "content": "Recent advancements in solar panel technology include perovskite cells with 30%+ efficiency, bifacial panels that capture light from both sides, and integrated storage systems...",
  "metadata": {
    "ragCitations": [
      {
        "id": "abc123",
        "displaySource": "Mind knowledge",
        "similarity": 0.89
      }
    ]
  }
}
```

<table>
<thead>
  <tr>
    <th>
      필드
    </th>
    
    <th>
      타입
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        messageId
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      추적을 위한 고유 메시지 식별자
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        content
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      마인드의 응답 텍스트 (구조화된 출력 사용 시 JSON 문자열)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parsed
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      파싱된 JSON 객체 (<code>
        response_format
      </code>
      
       사용 시에만 존재)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tool_calls
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      도구 호출 요청 배열 (사용자 정의 도구가 호출될 때만 존재). 각 요청은 <code>
        id
      </code>
      
      , <code>
        name
      </code>
      
      , <code>
        arguments
      </code>
      
      를 가집니다.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        metadata
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      선택적 메타데이터 (인용, 이미지)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        metadata.ragCitations
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      응답에 사용된 지식 출처 및 웹 검색 결과
    </td>
  </tr>
</tbody>
</table>

## 단일 메시지 예시

단일 질문하기:

```bash
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are the top 3 marketing trends for 2025?"
      }
    ]
  }'
```

## 멀티턴 대화

이전 메시지를 포함하여 대화 컨텍스트를 유지합니다:

```bash
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are the top marketing trends?"
      },
      {
        "role": "assistant",
        "content": "The top trends are AI personalization, short-form video, and community building..."
      },
      {
        "role": "user",
        "content": "How can I implement AI personalization on a budget?"
      }
    ]
  }'
```

**멀티턴 대화 팁:**

- 각 요청에 전체 대화 기록을 포함하세요
- 순서가 중요합니다: 메시지는 시간순이어야 합니다
- `user`와 `assistant` 역할을 번갈아 사용하세요
- 마지막 메시지는 항상 `user` 역할이어야 합니다

## 파일 첨부

파일, 문서, 이미지, 링크를 첨부하여 마인드에 컨텍스트를 제공하세요. 마인드는 처리된 콘텐츠를 대화의 일부로 받습니다.

### 파일 첨부하기

사용자 메시지의 `metadata.attachedFiles` 배열을 통해 파일을 추가하세요:

```bash
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Please review this document and summarize the key points",
        "metadata": {
          "attachedFiles": [
            {
              "url": "https://example.com/quarterly-report.pdf",
              "name": "Q4 2025 Report",
              "type": "application/pdf"
            },
            {
              "path": "uploads/meeting-notes.docx",
              "name": "Strategy Meeting Notes"
            }
          ]
        }
      }
    ]
  }'
```

### 첨부 파일 형식

각 첨부 파일 객체는 다음을 지원합니다:

<table>
<thead>
  <tr>
    <th>
      필드
    </th>
    
    <th>
      타입
    </th>
    
    <th>
      필수
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        url
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요*
    </td>
    
    <td>
      파일의 외부 URL (HTTP/HTTPS)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        path
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요*
    </td>
    
    <td>
      Supabase 스토리지 경로 (자동 서명됨)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      파일 표시 이름
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      MIME 타입 (예: <code>
        application/pdf
      </code>
      
      , <code>
        image/png
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      선택적 설명
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        transcription
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      사전 전사된 오디오/비디오 콘텐츠
    </td>
  </tr>
</tbody>
</table>

**참고:** `url` 또는 `path` 중 하나만 제공해야 하며, 둘 다 제공할 수는 없습니다.

### 지원 파일 형식

**문서:**

- PDF (`.pdf`) - 텍스트 추출 + 스캔된 페이지 OCR
- Word (`.docx`) - 전체 텍스트 추출
- Text (`.txt`, `.md`) - 직접 텍스트 콘텐츠
- CSV/Excel (`.csv`, `.xlsx`) - 표 추출

**이미지:**

- PNG, JPG, WEBP - OCR + 시각적 분석
- 이미지 이해를 위한 비전 기능

**외부 URL:**

- Firecrawl로 가져온 웹 페이지 (JS 렌더링 + 스크린샷)
- 자동 마크다운 변환

### 처리

파일은 마인드에 전송되기 전에 자동으로 처리됩니다:

1. **다운로드** - URL 또는 Supabase 스토리지에서 파일 가져오기
2. **추출** - 콘텐츠 추출 (PDF에서 텍스트, 이미지에서 OCR 등)
3. **주입** - 처리된 콘텐츠를 대화 컨텍스트에 추가
4. **응답** - 마인드가 메시지와 파일 콘텐츠를 모두 확인

**처리 제한:**

- 타임아웃: 파일당 30초
- 파일 병렬 처리
- 실패한 파일은 정상적인 대체 메시지 표시

### 다중 파일 예시

```json
{
  "messages": [
    {
      "role": "user",
      "content": "Compare these two proposals and recommend which one to pursue",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://example.com/proposal-a.pdf",
            "name": "Proposal A - Cloud Migration",
            "type": "application/pdf"
          },
          {
            "url": "https://example.com/proposal-b.pdf",
            "name": "Proposal B - On-Prem Upgrade",
            "type": "application/pdf"
          },
          {
            "path": "uploads/budget-analysis.xlsx",
            "name": "Budget Comparison"
          }
        ]
      }
    }
  ]
}
```

### 대화 기록의 파일 첨부

파일 첨부가 있는 대화를 계속할 때, 원본 메시지와 첨부 파일을 기록에 포함하세요:

```json
{
  "messages": [
    {
      "role": "user",
      "content": "Analyze this sales data",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://example.com/sales-q4.csv",
            "name": "Q4 Sales Data"
          }
        ]
      }
    },
    {
      "role": "assistant",
      "content": "Based on the Q4 sales data, I can see that revenue increased by 23% compared to Q3..."
    },
    {
      "role": "user",
      "content": "What were the top 3 performing products?"
    }
  ]
}
```

**참고:** 파일은 처음 첨부될 때 한 번만 처리됩니다. 동일한 대화의 후속 메시지는 이미 처리된 콘텐츠를 참조합니다.

### 웹 링크

웹 페이지 및 외부 콘텐츠의 경우 `url` 필드를 사용하세요:

```json
{
  "messages": [
    {
      "role": "user",
      "content": "Summarize the key findings from this research paper",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://arxiv.org/pdf/2103.12345.pdf",
            "name": "AI Research Paper",
            "type": "application/pdf"
          }
        ]
      }
    }
  ]
}
```

**특히 웹 페이지의 경우:**

- JavaScript가 많은 사이트는 Firecrawl로 렌더링됩니다
- 시각적 컨텍스트를 위해 스크린샷이 캡처됩니다
- 콘텐츠가 깔끔한 마크다운으로 변환됩니다

### 오류 처리

파일 처리가 실패하는 경우:

- 마인드는 파일이 첨부되었지만 처리에 실패했다는 대체 메시지를 받습니다
- 대화는 정상적으로 계속됩니다
- 타임아웃 오류는 `[Processing timeout - file may be too large]`를 표시합니다
- 기타 오류는 `[Processing failed - file uploaded but analysis unavailable]`를 표시합니다

이를 통해 처리가 실패하더라도 마인드가 첨부 시도를 인지할 수 있습니다.

## 초기 메시지 (인사말)

메시지 배열을 비우거나 메시지를 보내지 않으면 마인드가 자신을 소개합니다:

```bash
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": []
  }'
```

응답:

```json
{
  "content": "Hi! I'm Sarah, a marketing director with 15 years of experience in B2B SaaS. I specialize in growth marketing and data-driven strategies. What can I help you with today?"
}
```

## 모델 재정의

`model` 파라미터를 전달하여 상태 비저장 완료 요청에 사용되는 AI 모델을 선택적으로 재정의할 수 있습니다. 이는 벤치마킹, 비용 최적화 또는 다른 모델 동작을 테스트하는 데 유용합니다. 상태 저장 채팅 및 패널 엔드포인트는 더 엄격한 재정의 유효성 검사를 사용합니다: `model`와 `provider`를 함께 보내야 합니다.

```bash
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are your thoughts on sustainable packaging?"
      }
    ],
    "model": "gpt-4o-mini"
  }'
```

`model`가 지정되지 않은 경우 서버 기본값이 사용됩니다.

### 제공자

<table>
<thead>
  <tr>
    <th>
      제공자
    </th>
    
    <th>
      값
    </th>
    
    <th>
      예시 모델
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      OpenAI
    </td>
    
    <td>
      <code>
        openai
      </code>
    </td>
    
    <td>
      <code>
        gpt-5.6-sol
      </code>
      
      , <code>
        gpt-5.6-terra
      </code>
      
      , <code>
        gpt-5.6-luna
      </code>
      
      , <code>
        gpt-5.4
      </code>
      
      , <code>
        gpt-5-mini
      </code>
      
      , <code>
        gpt-4o
      </code>
      
      , <code>
        gpt-4o-mini
      </code>
      
      , <code>
        o3
      </code>
      
      , <code>
        o3-pro
      </code>
      
      , <code>
        o3-mini
      </code>
      
      , <code>
        o4-mini
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Anthropic
    </td>
    
    <td>
      <code>
        anthropic
      </code>
    </td>
    
    <td>
      <code>
        claude-fable-5
      </code>
      
      , <code>
        claude-opus-5
      </code>
      
      , <code>
        claude-sonnet-5
      </code>
      
      , <code>
        claude-haiku-4-5-20251001
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Google
    </td>
    
    <td>
      <code>
        google
      </code>
    </td>
    
    <td>
      <code>
        gemini-3.7-flash
      </code>
      
      , <code>
        gemini-3.5-flash-lite
      </code>
    </td>
  </tr>
</tbody>
</table>

제공자가 지원하는 모든 모델 문자열을 전달할 수 있습니다. 제공자는 일반적인 모델 이름 접두사(`claude-` → Anthropic, `gemini-` → Google, `gpt-`/`o1`/`o3`/`o4` → OpenAI)에서 자동 감지됩니다.

이름이 모호한 모델의 경우 `provider`를 명시적으로 지정하세요:

```json
{
  "messages": [...],
  "model": "my-custom-fine-tune",
  "provider": "openai"
}
```

제공자를 결정할 수 없는 경우 API는 이를 지정하라는 `400 Bad Request` 오류를 반환합니다.

## 구조화된 출력

`response_format` 파라미터를 사용하여 특정 스키마와 일치하는 보장된 JSON 응답을 요청합니다. 이는 OpenAI 스타일의 구조화된 출력 패턴을 따르며 대화에서 구조화된 데이터를 추출하는 데 유용합니다.

### JSON 스키마 모드

모델이 스키마와 일치하는 유효한 JSON을 출력하도록 강제합니다:

```bash
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Analyze the sentiment of this text: I love this product, it exceeded all my expectations!"
      }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "sentiment_analysis",
        "description": "Sentiment analysis result",
        "schema": {
          "type": "object",
          "properties": {
            "sentiment": {
              "type": "string",
              "enum": ["positive", "negative", "neutral"]
            },
            "confidence": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "keywords": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "required": ["sentiment", "confidence", "keywords"]
        }
      }
    }
  }'
```

응답:

```json
{
  "content": "{\"sentiment\": \"positive\", \"confidence\": 0.95, \"keywords\": [\"love\", \"exceeded\", \"expectations\"]}",
  "parsed": {
    "sentiment": "positive",
    "confidence": 0.95,
    "keywords": ["love", "exceeded", "expectations"]
  }
}
```

### JSON 객체 모드

스키마 유효성 검사 없이 JSON 출력을 강제합니다:

```bash
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "List 3 marketing ideas as JSON"
      }
    ],
    "response_format": {
      "type": "json_object"
    }
  }'
```

### 응답 형식 유형

<table>
<thead>
  <tr>
    <th>
      유형
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        text
      </code>
    </td>
    
    <td>
      기본 텍스트 출력 (현재 동작)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        json_object
      </code>
    </td>
    
    <td>
      스키마 유효성 검사 없이 유효한 JSON 출력을 강제합니다
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        json_schema
      </code>
    </td>
    
    <td>
      제공된 스키마와 일치하는 JSON 출력을 강제합니다
    </td>
  </tr>
</tbody>
</table>

### JSON 스키마 필드

<table>
<thead>
  <tr>
    <th>
      필드
    </th>
    
    <th>
      타입
    </th>
    
    <th>
      필수
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        예
      </strong>
    </td>
    
    <td>
      스키마의 식별자
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      스키마가 나타내는 것에 대한 설명
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        schema
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      <strong>
        예
      </strong>
    </td>
    
    <td>
      JSON 스키마 정의
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        strict
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      엄격한 스키마 준수 강제 (기본값: <code>
        true
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

### 지원되는 스키마 기능

다음 JSON 스키마 기능이 지원됩니다:

- **타입**: `string`, `number`, `integer`, `boolean`, `array`, `object`, `null`
- **제약 조건**: `enum`, `minimum`, `maximum`, `minLength`, `maxLength`, `minItems`, `maxItems`
- **구조**: `properties`, `required`, `items`, `additionalProperties`
- **메타데이터**: `description` (모델을 안내하는 데 사용됨)

### 참고

- 도구(RAG, 웹 검색 등)는 구조화된 출력과 함께 작동합니다. 마인드는 구조화된 응답을 생성하기 전에 지식 베이스를 검색할 수 있습니다.
- `parsed` 필드는 편의를 위해 파싱된 JSON 객체를 포함합니다. `content`는 원시 JSON 문자열을 포함합니다.
- 모든 주요 제공자(OpenAI, Anthropic, Google)는 구조화된 출력을 지원합니다.
- 복잡한 스키마의 경우, `description` 필드를 추가하여 모델의 출력을 유도하는 것을 고려하세요.

## 도구 호출

대화 중에 마인드가 사용자 지정 함수를 호출할 수 있도록 합니다. 이는 OpenAI 호환 함수 호출 패턴을 따르며 외부 도구 및 API로 마인드의 기능을 확장할 수 있게 해줍니다.

### 작동 방식

1. **도구 정의**: 이름, 설명, JSON 스키마 파라미터로 도구 정의를 전달합니다.
2. **마인드 결정**: 마인드는 대화에 따라 언제 도구를 호출할지 결정합니다 (또는 `tool_choice`로 강제할 수 있습니다).
3. **API가 도구 호출 반환**: 응답에는 도구 이름과 생성된 인수가 포함된 `tool_calls`가 포함됩니다.
4. **도구 실행**: 애플리케이션에서 도구를 실행하고 결과를 얻습니다.
5. **결과 다시 보내기**: `role: "tool"`를 사용하여 다음 메시지에 도구 결과를 포함합니다.
6. **마인드 응답**: 마인드는 도구 결과를 최종 응답에 통합합니다.

### 기본 예시

**도구가 포함된 요청:**

```bash
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the weather in Berlin?"
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "City name"
            },
            "units": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "Temperature units"
            }
          },
          "required": ["city"]
        }
      }
    ]
  }'
```

**응답:**

```json
{
  "content": "",
  "tool_calls": [
    {
      "id": "call_abc123",
      "name": "get_weather",
      "arguments": {
        "city": "Berlin",
        "units": "celsius"
      }
    }
  ]
}
```

**도구를 실행하고 결과를 다시 보냅니다:**

```bash
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the weather in Berlin?"
      },
      {
        "role": "assistant",
        "content": "",
        "tool_calls": [
          {
            "id": "call_abc123",
            "name": "get_weather",
            "arguments": {
              "city": "Berlin",
              "units": "celsius"
            }
          }
        ]
      },
      {
        "role": "tool",
        "tool_call_id": "call_abc123",
        "content": "{\"temperature\": 18, \"condition\": \"partly cloudy\", \"humidity\": 65}"
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string" },
            "units": { "type": "string", "enum": ["celsius", "fahrenheit"] }
          },
          "required": ["city"]
        }
      }
    ]
  }'
```

**최종 응답:**

```json
{
  "content": "The current weather in Berlin is 18°C and partly cloudy, with 65% humidity."
}
```

### 도구 정의 스키마

각 도구는 다음 구조를 따라야 합니다:

```json
{
  "name": "tool_name",
  "description": "Clear description of when and how to use this tool",
  "parameters": {
    "type": "object",
    "properties": {
      "param1": {
        "type": "string",
        "description": "What this parameter does"
      }
    },
    "required": ["param1"]
  },
  "strict": true
}
```

**필수 필드:**

<table>
<thead>
  <tr>
    <th>
      필드
    </th>
    
    <th>
      타입
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      함수 이름. 고유해야 하며 내부 도구와 충돌할 수 없습니다.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      도구가 무엇을 하는지, 언제 사용해야 하는지에 대한 명확한 설명. 이는 마인드의 도구 선택을 안내합니다.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parameters
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      함수 인수를 정의하는 JSON 스키마.
    </td>
  </tr>
</tbody>
</table>

**선택적 필드:**

<table>
<thead>
  <tr>
    <th>
      필드
    </th>
    
    <th>
      타입
    </th>
    
    <th>
      기본값
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        strict
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      인수에 대한 엄격한 스키마 유효성 검사를 강제합니다.
    </td>
  </tr>
</tbody>
</table>

### 도구 선택 모드

`tool_choice` 파라미터를 사용하여 마인드가 언제, 어떻게 도구를 호출할지 제어합니다:

<table>
<thead>
  <tr>
    <th>
      값
    </th>
    
    <th>
      동작
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        "auto"
      </code>
    </td>
    
    <td>
      마인드가 도구 호출 여부를 결정합니다 (기본값)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        "required"
      </code>
    </td>
    
    <td>
      마인드는 응답하기 전에 하나 이상의 도구를 호출해야 합니다
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        "none"
      </code>
    </td>
    
    <td>
      이 턴 동안 도구 호출을 비활성화합니다
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        {"name": "tool_name"}
      </code>
    </td>
    
    <td>
      마인드가 특정 도구를 호출하도록 강제합니다
    </td>
  </tr>
</tbody>
</table>

**예시:**

```json
// Let the mind decide
{
  "messages": [...],
  "tools": [...],
  "tool_choice": "auto"
}

// Force a specific tool
{
  "messages": [...],
  "tools": [...],
  "tool_choice": {
    "name": "search_database"
  }
}

// Require at least one tool call
{
  "messages": [...],
  "tools": [...],
  "tool_choice": "required"
}
```

### 병렬 도구 호출

기본적으로 마인드는 효율성을 위해 한 턴에 여러 도구를 호출할 수 있습니다:

```json
{
  "content": "",
  "tool_calls": [
    {
      "id": "call_1",
      "name": "get_customer",
      "arguments": { "id": "CUST-001" }
    },
    {
      "id": "call_2",
      "name": "get_customer",
      "arguments": { "id": "CUST-002" }
    }
  ]
}
```

병렬 호출을 비활성화하고 순차적 실행을 강제하려면:

```json
{
  "messages": [...],
  "tools": [...],
  "parallel_tool_calls": false
}
```

### 도구 메시지 형식

도구 결과를 다시 보낼 때 `tool` 역할을 사용하세요:

```json
{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "{\"result\": \"success\", \"data\": {...}}"
}
```

<table>
<thead>
  <tr>
    <th>
      필드
    </th>
    
    <th>
      타입
    </th>
    
    <th>
      필수
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        role
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        예
      </strong>
    </td>
    
    <td>
      <code>
        "tool"
      </code>
      
      여야 합니다
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tool_call_id
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        예
      </strong>
    </td>
    
    <td>
      어시스턴트 응답의 도구 호출에서 온 <code>
        id
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        content
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        예
      </strong>
    </td>
    
    <td>
      도구 실행 결과 (일반적으로 JSON 문자열)
    </td>
  </tr>
</tbody>
</table>

### 내부 도구 vs 사용자 도구

Minds에는 자동으로 실행되는 내장 서버 측 도구가 있습니다:

<table>
<thead>
  <tr>
    <th>
      내부 도구
    </th>
    
    <th>
      목적
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        GET_SPARK_RAG
      </code>
    </td>
    
    <td>
      마인드의 지식 베이스 검색
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        WEB_SEARCH
      </code>
    </td>
    
    <td>
      웹 검색
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GENERATE_IMAGE
      </code>
    </td>
    
    <td>
      AI로 이미지 생성
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DISPLAY_IMAGE
      </code>
    </td>
    
    <td>
      마인드의 메모리에서 이미지 표시
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DOCUMENT_PROCESSING
      </code>
    </td>
    
    <td>
      업로드된 파일 분석
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ANALYZE_LINK
      </code>
    </td>
    
    <td>
      웹 URL 가져오기 및 분석
    </td>
  </tr>
</tbody>
</table>

**주요 차이점:**

- **내부 도구**: 서버 측에서 실행되며, 결과는 `content` 및 `metadata`에 포함됩니다. `tool_calls`에는 절대 반환되지 않습니다.
- **사용자 도구**: 사용자가 실행할 수 있도록 `tool_calls`로 반환됩니다. 결과는 `tool` 메시지로 다시 보내야 합니다.

내부 도구를 재정의하거나 비활성화할 수 없습니다. 사용자 도구는 **추가적**입니다 - 마인드의 기능을 확장합니다.

### 전체 다중 도구 예시

여러 사용자 지정 도구를 갖춘 법률 보조 마인드:

```bash
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Create a new case for Schmidt vs. Mueller and search for similar precedents"
      }
    ],
    "tools": [
      {
        "name": "create_case",
        "description": "Create a new legal case in the system",
        "parameters": {
          "type": "object",
          "properties": {
            "title": {
              "type": "string",
              "description": "Case title (parties involved)"
            },
            "practice_area": {
              "type": "string",
              "enum": ["corporate", "litigation", "employment", "ip"],
              "description": "Legal practice area"
            },
            "client_id": {
              "type": "string",
              "description": "Client identifier"
            }
          },
          "required": ["title", "practice_area"]
        }
      },
      {
        "name": "search_precedents",
        "description": "Search legal database for similar cases",
        "parameters": {
          "type": "object",
          "properties": {
            "keywords": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Search keywords"
            },
            "practice_area": {
              "type": "string",
              "description": "Filter by practice area"
            },
            "max_results": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "description": "Maximum number of results"
            }
          },
          "required": ["keywords"]
        }
      }
    ],
    "parallel_tool_calls": true
  }'
```

**병렬 도구 호출이 포함된 응답:**

```json
{
  "content": "",
  "tool_calls": [
    {
      "id": "call_1",
      "name": "create_case",
      "arguments": {
        "title": "Schmidt vs. Mueller",
        "practice_area": "litigation"
      }
    },
    {
      "id": "call_2",
      "name": "search_precedents",
      "arguments": {
        "keywords": ["Schmidt", "Mueller"],
        "practice_area": "litigation",
        "max_results": 10
      }
    }
  ]
}
```

### 모범 사례

1. **명확한 설명 작성**: `description` 필드는 매우 중요합니다. 각 도구를 언제, 왜 사용해야 하는지 구체적으로 설명하세요.```json
❌ "description": "데이터베이스 검색"
✅ "description": "키워드 및 업무 분야를 기반으로 유사 사례에 대한 법률 판례 데이터베이스 검색"
```
2. **파라미터 설명 사용**: 마인드가 각 파라미터가 무엇을 하는지 이해하도록 돕습니다.```json
"case_id": {
  "type": "string",
  "description": "CASE-YYYY-NNNN 형식의 고유 사건 식별자"
}
```
3. **제한된 값에 대해 enum 활용**:```json
"status": {
  "type": "string",
  "enum": ["pending", "active", "closed", "archived"]
}
```
4. **유효성 검사 제약 조건 설정**:```json
"priority": {
  "type": "integer",
  "minimum": 1,
  "maximum": 5,
  "description": "우선순위 수준 (1=가장 낮음, 5=가장 높음)"
}
```
5. **엄격 모드 활성화**: 마인드가 유효한 인수를 생성하도록 하려면 `strict: true`(기본값)를 유지하세요.
6. **구조화된 도구 결과 반환**: 도구 결과에 JSON을 사용하여 쉽게 파싱할 수 있도록 합니다:```json
{
  "role": "tool",
  "tool_call_id": "call_123",
  "content": "{\"success\": true, \"case_id\": \"CASE-2026-001\", \"created_at\": \"2026-03-30T23:00:00Z\"}"
}
```
7. **오류를 정상적으로 처리**: 도구 결과에 오류 세부 정보를 반환합니다:```json
{
  "role": "tool",
  "tool_call_id": "call_123",
  "content": "{\"success\": false, \"error\": \"사건이 이미 존재합니다\", \"error_code\": \"DUPLICATE_CASE\"}"
}
```

### 제한 사항

- 요청당 **최대 128개 도구**
- 도구 이름은 고유해야 하며 내부 도구 이름과 충돌할 수 없습니다
- 도구 실행은 클라이언트 측에서 발생합니다 - 도구를 실행하고 보안을 유지하는 것은 사용자의 책임입니다
- 마인드가 응답하려면 도구 결과를 대화 기록에 다시 보내야 합니다

### JSON 스키마 지원

`parameters` 필드는 표준 JSON 스키마 기능을 지원합니다:

**타입:**

- `string`, `number`, `integer`, `boolean`, `array`, `object`, `null`

**유효성 검사:**

- `enum` , 특정 값으로 제한
- `minimum`, `maximum` , 숫자 범위
- `minLength`, `maxLength` , 문자열 길이
- `minItems`, `maxItems` , 배열 크기
- `pattern` , 정규식 유효성 검사
- `format` , 문자열 형식 (예: `"date-time"`, `"email"`, `"uri"`)

**구조:**

- `properties` , 객체 속성
- `required` , 필수 필드
- `items` , 배열 항목 스키마
- `additionalProperties` , 추가 속성 허용/비허용

**고급 유효성 검사 예시:**

```json
{
  "name": "schedule_meeting",
  "description": "Schedule a meeting with a client",
  "parameters": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      },
      "date": {
        "type": "string",
        "format": "date-time",
        "description": "Meeting date and time in ISO 8601 format"
      },
      "attendees": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "email"
        },
        "minItems": 1,
        "maxItems": 20
      },
      "duration_minutes": {
        "type": "integer",
        "minimum": 15,
        "maximum": 480,
        "description": "Meeting duration (15-480 minutes)"
      }
    },
    "required": ["title", "date", "attendees"]
  }
}
```

## 작동 방식

### 1. 컨텍스트 로딩

메시지를 보내면 마인드는 다음을 수행합니다:

- 시스템 프롬프트와 구성을 로드합니다
- **지식 베이스에서 관련 정보를 자동으로 검색합니다**
- 대화 기록을 고려합니다

### 2. 처리

마인드는 다음을 수행합니다:

- 컨텍스트 내에서 메시지를 분석합니다
- **검색된 지식에 기반하여 응답의 근거를 제시하고** 인용을 포함합니다
- 필요한 경우 추가 도구(웹 검색, 이미지 생성 등)에 접근합니다
- 자신의 페르소나에 맞는 응답을 구성합니다

### 3. 응답 생성

마인드는 다음을 수행합니다:

- 전문성을 반영하는 응답을 생성합니다
- 지식 베이스나 웹 출처를 사용할 때 **인용을 포함합니다**
- 선택적 메타데이터(인용, 이미지 등)와 함께 메시지를 반환합니다

## 메타데이터

응답에는 추가 메타데이터가 포함될 수 있습니다:

### 이미지

마인드가 이미지를 생성하거나 표시할 때:

```json
{
  "content": "Here are some logo concepts...",
  "metadata": {
    "images": [
      {
        "id": "img_123",
        "url": "https://...",
        "filename": "Logo Concept 1",
        "description": "Modern minimalist logo with blue gradient",
        "source": "generated"
      }
    ]
  }
}
```

### 지식 인용

마인드가 지식 베이스나 웹 검색에서 정보를 검색할 때:

```json
{
  "content": "Based on recent research, solar panel efficiency has improved significantly...",
  "metadata": {
    "ragCitations": [
      {
        "id": "9bf44ab0-9d83-42ec-b941-c0ab7610e949",
        "displaySource": "Mind knowledge",
        "similarity": 0.85
      },
      {
        "id": "external-web-123",
        "displaySource": "https://example.com/solar-research",
        "similarity": 0.92
      }
    ]
  }
}
```

**인용 필드:**

- `id` - 출처의 고유 식별자
- `displaySource` - 사람이 읽을 수 있는 출처 이름 또는 URL
- `similarity` - 관련성 점수 (0-1), 출처가 쿼리와 얼마나 잘 일치하는지를 나타냄

마인드는 응답하기 전에 자동으로 지식 베이스를 검색하고, 특정 출처에 근거하여 답변할 때 인용을 포함합니다.

## 접근 제어

다음과 같은 마인드와 채팅할 수 있습니다:

- **소유한 마인드** - 직접 생성한 마인드
- **접근 권한이 있는 마인드** - 팀원이 공유한 마인드
- **멤버로 속한 마인드** - 소속된 팀 워크스페이스의 마인드
- **공개 마인드** - 공개적으로 접근 가능한 마인드

권한이 없는 마인드에 접근하려고 하면 다음이 반환됩니다:

```json
{
  "statusCode": 403,
  "statusMessage": "Access denied"
}
```

## 응답 형식

### 텍스트 응답

대부분의 응답은 일반 텍스트입니다:

```json
{
  "content": "Based on current trends, I recommend focusing on..."
}
```

### 구조화된 응답

일부 마인드는 구조화된 콘텐츠를 반환할 수 있습니다:

```json
{
  "content": "Here's my analysis:\n\n1. Trend: AI Personalization\n   - Impact: High\n   - Timeline: 6-12 months\n\n2. Trend: Short-form Video\n   - Impact: Very High\n   - Timeline: Immediate"
}
```

### 메타데이터만 있는 빈 응답

때로는 메타데이터만 반환됩니다 (예: 이미지 생성 시):

```json
{
  "content": "",
  "metadata": {
    "images": [...]
  }
}
```

## 모범 사례

### 구체적으로 질문하기

```text
❌ "Tell me about marketing"
✅ "What are the most cost-effective digital marketing channels for a B2B SaaS startup with a $5K monthly budget?"
```

### 컨텍스트 제공하기

```text
✅ "We're launching a sustainable fashion brand targeting Gen Z. What social media strategy would you recommend?"
```

### 후속 질문 사용하기

대화 기억 기능을 활용하세요:

```text
User: "What are the top trends?"
Assistant: "The top trends are..."
User: "Which of these would work best for a small budget?"
Assistant: "For a small budget, I'd focus on..."
```

### 지식 참조하기

지식을 업로드했다면 참조하세요:

```text
✅ "Based on our brand guidelines, what tone should we use for this campaign?"
```

## 오류 응답

### 400 Bad Request

Mind ID가 누락되었거나 유효하지 않음:

```json
{
  "statusCode": 400,
  "statusMessage": "Mind ID is required"
}
```

지원되지 않는 제공자:

```json
{
  "statusCode": 400,
  "statusMessage": "Unsupported provider: 'invalid'. Supported providers: openai, anthropic, google."
}
```

제공자 없이 모호한 모델 이름 사용:

```json
{
  "statusCode": 400,
  "statusMessage": "Cannot auto-detect provider for model 'my-model'. Please specify a 'provider' parameter (openai, anthropic, or google)."
}
```

### 401 Unauthorized

유효하지 않은 API 키.

### 403 Forbidden

Mind에 대한 접근 거부:

```json
{
  "statusCode": 403,
  "statusMessage": "Access denied"
}
```

### 404 Not Found

Mind가 존재하지 않음:

```json
{
  "statusCode": 404,
  "statusMessage": "Mind not found"
}
```

## 사용 참고 사항

- v1 API는 인증된 계정별로 설정 가능한 제한(기본값 분당 300개 요청)을 적용합니다
- `RateLimit-Limit`와 `RateLimit-Remaining`을 읽고 `429` 이후에는 `Retry-After`를 따르세요
- 생성 요청은 리소스를 많이 사용하므로 병렬 completion 수를 제한하세요

## 다음 단계

- [지연 시간 및 성능](/docs/api/latency) 이해하기
- [오류 및 속도 제한](/docs/api/errors)에 대해 알아보기
- 첫 [마인드](/docs/api/minds) 생성하기
- 응답 향상을 위해 [지식](/docs/api/knowledge) 업로드하기
- [API 개요](/docs/api/overview) 읽기