인증, 액세스 및 청구
https://api.krea.ai로 보내는 모든 요청에 Authorization: Bearer KREA_API_KEY를 포함하세요. 개인, 서비스 및 레거시 API 키는 표준 공개 API 인증을 사용합니다.
인증된 워크스페이스에서 인증된 호출자가 소유한 세션만 읽거나 이어갈 수 있습니다. 세션 ID를 안다고 해서 액세스 권한이 부여되지는 않습니다. Krea 파일 첨부도 해당 워크스페이스에서 해당 호출자가 액세스할 수 있어야 합니다.
에이전트 턴은 워크스페이스의 컴퓨트 유닛 잔액을 사용합니다. API 잔액은 사용하지 않습니다. 에이전트 플랜 권한과 Free 플랜 메시지 한도는 그대로 적용됩니다. 에이전트 플랜, 액세스 및 크레딧을 참조하세요.
url이 포함되어 있으며, 적절한 계정 및 워크스페이스 액세스 권한이 있으면 이 URL로 Krea 앱에서 세션을 열 수 있습니다.
세션을 시작하고 결과 기다리기
먼저 환경에KREA_API_KEY를 설정하세요. curl과 jq를 사용하는 Bash, requests를 사용하는 Python, 또는 내장 fetch나 Krea SDK를 사용하는 Node.js 중에서 선택하세요.
1
첫 번째 턴 제출
세션을 만들려면
sessionId를 생략하세요. 반환된 sessionId와 runId를 저장하세요. 응답은 status: "running"과 함께 즉시 반환됩니다.2
이 턴 기다리기
두 ID를 모두
wait-for-session에 전달하세요. timedOut이 true이면 같은 ID로 다시 호출하세요. 타임아웃이 발생해도 턴은 취소되지 않습니다.3
결과 읽기
finished가 true이면 status를 확인하세요. text, media 및 error가 있는지 살펴보거나, 반환된 url을 여세요.pip install requests로 requests를 설치하세요. Node.js의 경우 Node.js 22 이상을 사용하고 예제를 example.mjs로 저장하세요. SDK 예제는 npm install @krea-ai/sdk가 필요하며, requestRaw를 사용해 HTTP 엔드포인트를 호출합니다.
이 예제들은 메시지 하나를 제출하고 최대 5분 동안 기다립니다. HTTP 오류가 발생하거나 턴이 실패 또는 취소되면 중단됩니다. 전송을 자동으로 재시도하지 않습니다. 전송 요청이 타임아웃되면 다시 제출하기 전에 Krea에서 세션을 확인하세요. 첫 번째 요청이 이미 턴을 시작했을 수 있습니다.
대기 시간 예산이 소진되어도 턴은 백그라운드에서 계속 진행됩니다. 나중에 대기를 재개할 수 있도록 출력된 세션 ID와 실행 ID를 저장하세요.
timeoutSeconds는 1에서 300 사이의 정수이며 기본값은 60입니다. HTTP 클라이언트 타임아웃은 요청한 대기 시간보다 길게 설정하세요. 전송 후 기다릴 때는 항상 최신 runId를 전달하여, 이전 턴의 종료 상태를 새 턴의 상태로 오인하지 않도록 하세요.
기다리지 않고 읽기
GET /agent/session/{sessionId}를 사용해 현재 세션의 스냅샷을 가져오세요:
cURL
세션 이어가기
턴이 끝나면 해당sessionId와 함께 다른 메시지를 보내세요:
cURL
code: "conflict"와 함께 409가 반환됩니다.
입력 및 첨부 파일
send-message는 다음 필드를 받습니다. 전체 모델 enum과 스키마는 레퍼런스를 참조하세요.
첨부 파일
url에는 액세스 가능한 HTTP(S) URL 또는 file:550e8400-e29b-41d4-a716-446655440000 같은 승인된 Krea Files URI를 사용할 수 있습니다. 선택 사항인 name과 contentType은 앞뒤 공백이 제거된, 비어 있지 않은 최대 255자의 문자열입니다. 호출자 로컬 경로와 OpenAI file_ ID는 지원되지 않습니다. 먼저 실제 파일을 전송하세요. 프롬프트 텍스트에 ID를 넣는다고 해서 파일 내용이 전송되지는 않습니다.
에이전트는 애플리케이션의 대화나 첨부 파일을 물려받지 않습니다. 달리 액세스할 수 없는 레퍼런스 파일은 첨부하세요. 프롬프트에 포함된 사용 가능한 URL, 기존 Krea 컨텍스트, 이전 세션 파일은 다시 첨부할 필요가 없습니다.
세션 결과
send-message는 sessionId, threadId, runId, status(항상 "running"), url을 반환합니다.
GET /agent/session/{sessionId}와 wait-for-session은 다음 세션 뷰를 반환합니다. wait-for-session만 필수 필드인 timedOut을 추가합니다.
각
media 항목은 생성물(jobId 및 선택 사항인 mediaKind: image, video, audio 또는 3d), 재호스팅된 미디어(url, 선택 사항인 mimeType 포함), 또는 Krea 파일(uri, name, mimeType)을 나타낼 수 있습니다. 생성 세부 정보는 GET /jobs/{jobId}로 가져오세요. Krea 파일 URI는 첨부 파일로 재사용하거나, 세션의 url을 열어 파일을 확인할 수 있습니다. 미디어는 턴이 아직 실행 중일 때도 나타날 수 있습니다.
오류
엔드포인트 오류는{ "error": "...", "code": "...", "allowedModels": ["..."] } 형식을 사용합니다. error만 필수입니다. 제출 후 실패한 턴은 대신 성공한 세션 응답에서 status: "failed"로 나타납니다.