# 작업 — /v1/tasks

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

> 원문: https://oneport.kr/docs/reference/tasks

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

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

**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 | 기존 작업실의 작업 상한이에요. 시작 전 지갑·키·그룹 한도를 확인하고 잔액 일부를 예약합니다. 실제 차감액은 정산에서 확인하세요. |
| `title` | 1~120자 | 선택할 수 있는 작업 이름이에요. 나머지 알 수 없는 필드는 거절합니다. |

**작업 만들기 — 이 요청 키를 보관하세요**

```bash
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 한 번의 제한 시간과 작업 전체의 수명은 서로 다릅니다.

작업 API는 맡긴 글·진행 기록·결과 답과 파일을 이용 계정이 닫히거나 키가 삭제될 때까지 저장해요. 만든 키·계정·그룹이 같을 때 조회할 수 있어요. 키 끄기나 DELETE로 작업을 취소해도 저장된 내용은 삭제되지 않아요.

## 조회·취소·결과물

| 요청 | 동작 |
| --- | --- |
| 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로 한 번 전하고 연결을 닫습니다. 이벤트 전체 이력은 보관하지 않습니다. |

**작업 응답의 주요 필드**

| 파라미터 | 받는 값 | 저희가 하는 일 |
| --- | --- | --- |
| `state` | starting · running · finalizing · cancelling · unknown · completed · cancelled · failed · rejected | unknown은 실행 결과를 확인 중이라는 뜻이에요. 새 요청 키로 다시 실행하지 마세요. rejected는 실행 전 거절입니다. |
| `result` | 문자열 또는 null | 저장된 작업 결과예요. 결과 파일 목록은 artifacts에서 읽습니다. |
| `artifacts` | 파일 배열 | id·filename·mime_type·bytes·url을 제공합니다. version은 불변 파일 ID, parent_version은 수정 전 파일 ID이며 없으면 null이에요. |
| `billing.state` | pending · settled · not_started | 실행 상태와 정산 상태를 함께 확인하세요. 파일 저장을 확인하기 전에는 완료 정산을 보류합니다. not_started는 실행 전 거절이 확인된 경우예요. |
| `billing.charged_nano` | 숫자 또는 null | 기존 지갑의 nano 단위 실제 차감액이에요. null은 미확정이며 0원이 아닙니다. reserved_nano는 미리 잡은 금액입니다. |
| `cancellation_requested` | true · false | 취소 요청이 저장됐는지를 알려 줍니다. true만으로 공급사 중지나 정산 완료를 뜻하지 않아요. |

**같은 키로 조회하고 저장된 파일 받기**

```bash
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를 사용하세요. 재연결은 기존 작업을 조회하며 새 생성을 하지 않습니다.

> **⚠️ 요청 결과를 모르면 같은 요청 키를 유지하세요**
>
> 401은 유효하지 않은 API 키, 403은 학생 키 제한, 404는 이 키에서 접근할 수 없는 작업·파일, 409는 같은 요청 키의 본문 충돌입니다. 잔액 부족은 402, 키·그룹 한도나 열린 작업 상한은 429, 조회 불가는 503으로 구분해요. 처리 불명이나 503을 0원·실패 확정으로 바꾸지 마세요. 같은 API 키의 같은 요청만 재조회하고, 키·그룹이 바뀌면 원래 작업에 접근할 수 없습니다.