콘텐츠로 이동

파일 업로드

업로드는 세 단계로 이루어집니다: 업로드 주소 요청, 파일 전송, 문서 확인. 업로드 주소는 한 번 발급받을 수 있으며 최대 1시간 동안 유효합니다.

POST /api/v1/upload/presign
X-API-Key: sk_your_key
Content-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
}

PUT을 본문으로 원시 파일 바이트를 포함하여 upload_url로 전송하고, upload_headers의 모든 헤더는 주어진 그대로 정확히 전송하십시오.

Terminal window
# UPLOAD_URL and UPLOAD_CONTENT_TYPE come from upload_url and upload_headers["Content-Type"] in the previous response
curl --fail-with-body -X PUT "$UPLOAD_URL" \
-H "Content-Type: $UPLOAD_CONTENT_TYPE" \
-H "If-None-Match: *" \
--upload-file "report.docx"

이 단계에서는 OmniDoc API 키를 전송하지 마십시오. 주소가 만료되거나 전송에 실패한 경우, 새 키를 요청하십시오.

POST /api/v1/upload/finalize
X-API-Key: sk_your_key
Content-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이 유효하지 않거나 만료되었습니다.
403finalize_token은 다른 계정에 속합니다.
410업로드된 파일을 찾을 수 없습니다(전송이 완료되지 않았거나 주소가 만료됨); 새 주소를 요청하십시오.
413파일당 크기 제한을 초과합니다.
415지원되지 않는 형식이거나 콘텐츠가 확장자와 일치하지 않습니다.
422Office 파일이 손상되었거나 구조적으로 안전하지 않습니다.
429업로드 수가 너무 많습니다
503업로드 서비스가 일시적으로 사용할 수 없습니다. 나중에 다시 시도해 주세요.