파일 업로드
업로드는 세 단계로 이루어집니다: 업로드 주소 요청, 파일 전송, 문서 확인. 업로드 주소는 한 번 발급받을 수 있으며 최대 1시간 동안 유효합니다.
1. 업로드 주소 요청
섹션 제목: “1. 업로드 주소 요청”POST /api/v1/upload/presignX-API-Key: sk_your_keyContent-Type: application/json{ "filename": "report.docx", "file_size": 45678}| 필드 | 유형 | 필수 | 설명 |
|---|---|---|---|
filename | 문자열 | ✅ | 파일 이름; 서버는 확장자로 파일 유형을 판단합니다. |
file_size | 정수 | ✅ | 바이트 단위의 정확한 크기이며 0보다 커야 합니다. |
mime_type | 문자열 | — | 선택 사항; 서버는 이를 사용하지 않습니다. |
응답:
{ "document_id": "4q8mx2q9z1k7p6ra", "upload_url": "https://upload.example/...", "upload_headers": { "Content-Type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "If-None-Match": "*" }, "finalize_token": "short_lived_token", "expires_in": 3600}2. 파일을 보내세요
섹션 제목: “2. 파일을 보내세요”PUT을 본문으로 원시 파일 바이트를 포함하여 upload_url로 전송하고, upload_headers의 모든 헤더는 주어진 그대로 정확히 전송하십시오.
# UPLOAD_URL and UPLOAD_CONTENT_TYPE come from upload_url and upload_headers["Content-Type"] in the previous responsecurl --fail-with-body -X PUT "$UPLOAD_URL" \ -H "Content-Type: $UPLOAD_CONTENT_TYPE" \ -H "If-None-Match: *" \ --upload-file "report.docx"이 단계에서는 OmniDoc API 키를 전송하지 마십시오. 주소가 만료되거나 전송에 실패한 경우, 새 키를 요청하십시오.
3. 문서를 확인합니다
섹션 제목: “3. 문서를 확인합니다”POST /api/v1/upload/finalizeX-API-Key: sk_your_keyContent-Type: application/json{"finalize_token":"short_lived_token"}성공 시 문서가 반환됩니다:
{ "document": { "id": "4q8mx2q9z1k7p6ra", "basename": "report.docx", "file_size": 45678, "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "created_at": "2026-10-01T12:00:00Z" }}확인 후에야 문서가 파일 라이브러리에 등록되어 작업에 사용할 수 있게 됩니다.
파일 이름
섹션 제목: “파일 이름”filename은 표시용으로만 사용되며 경로나 고유 식별자로 사용해서는 안 됩니다. 서버는 불법 문자를 대체하고 너무 긴 이름의 경우 안전한 다운로드 이름을 생성합니다.
| 상태 | 원인 |
|---|---|
400 | 잘못된 파일 이름 또는 크기이거나, 업로드된 크기가 요청한 크기와 다릅니다. |
401 | 자격 증명 또는 finalize_token이 유효하지 않거나 만료되었습니다. |
403 | finalize_token은 다른 계정에 속합니다. |
410 | 업로드된 파일을 찾을 수 없습니다(전송이 완료되지 않았거나 주소가 만료됨); 새 주소를 요청하십시오. |
413 | 파일당 크기 제한을 초과합니다. |
415 | 지원되지 않는 형식이거나 콘텐츠가 확장자와 일치하지 않습니다. |
422 | Office 파일이 손상되었거나 구조적으로 안전하지 않습니다. |
429 | 업로드 수가 너무 많습니다 |
503 | 업로드 서비스가 일시적으로 사용할 수 없습니다. 나중에 다시 시도해 주세요. |