첫 API 호출하기 — curl 한 줄로 내 AI에게 질문하기

FlameBox를 설치하고 계정에 연결했다면, 이제 내 PC나 서버의 AI에게 API로 말을 걸 차례입니다. 이 글에서는 Cortex 만들기 → 주소와 키 확인 → curl로 호출까지 따라 해 보고, FlameAI API만의 특징인 "이어서 대화하기"도 함께 살펴봅니다.

아직 FlameBox를 설치하지 않았다면 Windows 편 또는 Linux 편을 먼저 봐 주세요.

1. Cortex 만들기

Cortex는 FlameBox에 모델을 올려서 API로 부를 수 있게 만든 것입니다. API를 호출할 때는 항상 "어느 Cortex에게 보낼지"를 지정합니다.

1. 마이페이지 › FlameBox에서 내 FlameBox를 엽니다.
2. 다운로드한 모델이 없다면 모델 다운로드로 모델을 하나 받습니다. 처음이라면 내 PC 메모리에 맞는 작은 모델부터 시작하는 것이 좋습니다.
3. Cortex 생성을 눌러 Cortex ID(예: my-assistant)를 정하고, 다운로드한 모델을 고른 뒤 생성합니다.

여기서 정한 Cortex ID가 API 주소에 그대로 들어갑니다.

2. 주소와 키 확인

마이페이지 › My API에서 두 가지를 확인합니다.

Secret Key는 비밀번호와 같습니다. 코드 저장소나 화면 캡처에 노출되지 않게 주의하고, 유출됐다면 My API 화면의 변경으로 바로 재발급하세요.

My API 화면 아래쪽 How to call에서 Cortex를 고르면, 내 주소와 Cortex ID가 채워진 curl·Java·Python·TypeScript 예시를 바로 복사할 수 있습니다.

3. 첫 호출

아래 명령에서 API 주소, Cortex ID, Secret Key를 내 값으로 바꿔 실행합니다.

curl -X POST https://api-3.flameai.im/Nx7bQ2mZ/cortex/my-assistant/messages \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "chat-001",
    "messages": [
      { "role": "user", "content": "안녕하세요! 자기소개를 한 문장으로 해 주세요." }
    ]
  }'

주소 형식은 {API 주소}/cortex/{Cortex ID}/messages입니다. conversationId는 이 대화를 구분하는 이름으로, 내 앱의 채팅방 ID 같은 값을 그대로 써도 됩니다.

잠시 뒤 아래와 같은 JSON이 돌아옵니다. 답변 본문은 message.content 안에서 type이 text인 블록에 있습니다.

{
  "cortexId": "my-assistant",
  "conversationId": "chat-001",
  "message": {
    "id": "msg-1714000000001",
    "role": "assistant",
    "content": [
      { "type": "text", "text": "안녕하세요, 저는 당신의 FlameBox에서 동작하는 AI 비서입니다." }
    ],
    "usage": { "input_tokens": 21, "output_tokens": 18, "elapsed_ms": 640 }
  }
}

모델에 따라 type이 thinking인 블록(모델이 답하기 전에 생각한 내용)이 먼저 올 수도 있습니다. 화면에 보여 줄 답은 text 블록만 읽으면 됩니다.

Cortex가 메모리에서 내려가 있던 상태라면 첫 요청 때 모델을 다시 올리느라 응답이 조금 늦을 수 있습니다. 두 번째 요청부터는 빨라집니다.

4. 이어서 대화하기

FlameAI API에서 가장 다른 점이 여기 있습니다. 일반적인 AI API는 매번 지금까지의 대화 전체를 다시 보내야 하지만, FlameBox의 Cortex는 앞의 대화를 기억하고 있습니다. 같은 conversationId로 새 메시지만 보내면 됩니다.

curl -X POST https://api-3.flameai.im/Nx7bQ2mZ/cortex/my-assistant/messages \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "chat-001",
    "messages": [
      { "role": "user", "content": "방금 한 자기소개를 영어로 바꿔 주세요." }
    ]
  }'

대화가 길어질수록 매번 보내는 데이터가 줄고, 앞부분을 다시 계산하지 않아 응답도 빨라집니다.

단, Cortex 하나는 한 번에 대화 하나만 맡습니다. 다른 conversationId로 보내면 cortex_occupied 오류가 나는데, 새 대화로 넘어가려면 options.cortex_reset을 true로 보내면 됩니다. 그러면 이전 대화를 비우고 새 대화로 시작합니다.

{
  "conversationId": "chat-002",
  "options": { "cortex_reset": true },
  "messages": [ { "role": "user", "content": "새로운 주제로 이야기해요." } ]
}

5. 글자가 나오는 대로 받기 (스트리밍)

채팅 화면처럼 답이 한 글자씩 나오게 하려면 options.stream을 true로 보냅니다. 응답이 SSE(text/event-stream) 형식으로 조금씩 도착합니다.

{
  "conversationId": "chat-001",
  "options": { "stream": true },
  "messages": [ { "role": "user", "content": "짧은 시 한 편 써 주세요." } ]
}

message.delta 이벤트로 글자 조각이 차례로 오고, 마지막 message.completed 이벤트에 완성된 답 전체가 한 번 더 담겨 옵니다. 이벤트 형식은 API 매뉴얼의 "대화 요청"에 정리되어 있습니다.

자주 만나는 오류

다음 단계

이제 내 FlameBox의 AI를 어디서든 부를 수 있게 되었습니다. 상태 보기, 추론 중지, 컨텍스트 초기화 같은 나머지 기능은 API 매뉴얼에서 확인할 수 있습니다. 다음 글에서는 이 API로 실제 무언가를 만들어 보겠습니다.