본문으로 건너뛰기
원포트 AI
로그인

작업 — /v1/tasks

작업을 한 번 시작하고, 진행과 정산을 조회하거나 저장된 결과 파일을 받습니다.

AI 에게 넘기기원문 열기

기존 API 키로 문서 작업을 맡기는 비동기 API예요. 웹 작업실과 같은 실행·지갑 예약·키 및 그룹 한도·정산을 사용합니다. 현재는 아래 작업 모델만 받으며 일반 채팅 API의 모델 목록과 달라요. 웹 대화·기관 자료·커넥터·예약을 자동으로 가져오지 않습니다.

작업 모델선택 방법
claude-sonnet-5-5model에 명시
claude-opus-5-5model에 명시
claude-haiku-5-5model에 명시

POST /v1/tasks — JSON 본문과 요청 헤더

파라미터받는 값저희가 하는 일
Authorization필수Bearer API 키이 키·계정·그룹에 작업을 묶어요. 학생 키는 실행과 조회가 제한됩니다.
Idempotency-Key필수공백 없는 ASCII 8~200자같은 키와 같은 요청은 원래 작업을 돌려줍니다. 요청 본문이 달라지면 409예요. 연결이 끊겨도 값을 유지하세요.
input필수비어 있지 않은 문자열, 최대 20,000자작업할 내용이에요. 첨부나 웹 대화의 내용을 별도 권한 없이 읽지 않아요.
model필수claude-sonnet-5-5 · claude-opus-5-5 · claude-haiku-5-5위 목록 중 하나를 명시해야 해요. 기본 모델을 임의로 골라 실행하지 않아요.
budget필수small · normal · large기존 작업실의 작업 상한이에요. 시작 전 지갑·키·그룹 한도를 확인하고 잔액 일부를 예약합니다. 실제 차감액은 정산에서 확인하세요.
title1~120자선택할 수 있는 작업 이름이에요. 나머지 알 수 없는 필드는 거절합니다.
작업 만들기 — 이 요청 키를 보관하세요
curl https://oneport.kr/v1/tasks \
  -H "Authorization: Bearer $ONEPORT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: reply-document-001' \
  -d '{"model":"claude-sonnet-5-5","budget":"small","input":"회의 안내 초안을 DOCX로 만들어 주세요."}'

JSON 전체는 100,000바이트까지예요. 생성 응답은 진행 중이면 202, 이미 끝난 같은 요청의 재조회는 200입니다. Location의 주소와 응답 id를 보관하세요. 한 키에서 열어 둔 작업은 3건까지이며 처리 불명 작업도 포함해요. HTTP 한 번의 제한 시간과 작업 전체의 수명은 서로 다릅니다.

조회·취소·결과물#

요청동작
GET /v1/tasks/{id}원래 작업의 최신 진행·결과·파일 버전·정산을 조회합니다. 진행 중이면 Retry-After를 따라 다시 조회하세요.
DELETE /v1/tasks/{id}취소 의도를 먼저 저장합니다. 공급사 중지를 확인하는 동안 202이며, 확인될 때까지 같은 작업을 조회합니다. 취소 전 사용한 비용이 정산될 수 있어요.
GET /v1/tasks/{id}/files/{fileId}artifacts[].url로 저장된 결과 파일을 받습니다. 다운로드는 새 생성이나 추가 작업을 시작하지 않습니다.
GET /v1/tasks/{id}/events최신 스냅샷을 event: task인 SSE로 한 번 전하고 연결을 닫습니다. 이벤트 전체 이력은 보관하지 않습니다.

작업 응답의 주요 필드

파라미터받는 값저희가 하는 일
statestarting · running · finalizing · cancelling · unknown · completed · cancelled · failed · rejectedunknown은 실행 결과를 확인 중이라는 뜻이에요. 새 요청 키로 다시 실행하지 마세요. rejected는 실행 전 거절입니다.
result문자열 또는 null저장된 작업 결과예요. 결과 파일 목록은 artifacts에서 읽습니다.
artifacts파일 배열id·filename·mime_type·bytes·url을 제공합니다. version은 불변 파일 ID, parent_version은 수정 전 파일 ID이며 없으면 null이에요.
billing.statepending · settled · not_started실행 상태와 정산 상태를 함께 확인하세요. 파일 저장을 확인하기 전에는 완료 정산을 보류합니다. not_started는 실행 전 거절이 확인된 경우예요.
billing.charged_nano숫자 또는 null기존 지갑의 nano 단위 실제 차감액이에요. null은 미확정이며 0원이 아닙니다. reserved_nano는 미리 잡은 금액입니다.
cancellation_requestedtrue · false취소 요청이 저장됐는지를 알려 줍니다. true만으로 공급사 중지나 정산 완료를 뜻하지 않아요.
같은 키로 조회하고 저장된 파일 받기
curl https://oneport.kr/v1/tasks/$TASK_ID -H "Authorization: Bearer $ONEPORT_API_KEY"
curl https://oneport.kr/v1/tasks/$TASK_ID/files/$FILE_ID -H "Authorization: Bearer $ONEPORT_API_KEY" -o result.docx
curl -X DELETE https://oneport.kr/v1/tasks/$TASK_ID -H "Authorization: Bearer $ONEPORT_API_KEY"

SSE의 id를 다음 요청의 Last-Event-ID 헤더로 보내세요. 상태가 같으면 데이터 이벤트 없이 retry: 3000만 돌려줍니다. 인증 헤더를 보낼 수 있는 SSE 클라이언트나 fetch를 사용하세요. 재연결은 기존 작업을 조회하며 새 생성을 하지 않습니다.