파일 - Conare

두 라우트가 하나의 파서, 같은 옵션, 같은 결과로 파일을 읽습니다:

라우트	동작	크기
`POST /namespaces/:namespace/files`	파일을 하나의 검색 가능한 문서로 저장합니다. 검색은 답하는 페이지, 슬라이드 또는 행을 알려 줍니다	최대 512 MiB, 5,000페이지
`POST /parse`	파일을 Markdown으로 반환하며, 아무것도 저장하지 않습니다	최대 20 MiB

스캔과 이미지는 페이지 수와 관계없이 OCR로 읽습니다. 지원 형식: 파일 형식.

파일 업로드

POST /namespaces/:namespace/files 파일 바이트를 본문으로 보내거나, multipart 폼의 파일 부분으로 보내거나, Conare가 가져오도록 JSON {"url": "https://..."}로 보내세요.

curl "https://api.conare.ai/namespaces/reports/files?name=report.pdf" \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

curl https://api.conare.ai/namespaces/reports/files \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -F file=@report.pdf

curl https://api.conare.ai/namespaces/reports/files \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/report.pdf"}'

import { readFile } from "node:fs/promises";

const reports = conare.namespace("reports");
const file = await reports.uploadFile(await readFile("report.pdf"), "report.pdf", {
  metadata: { site: "north-pit" },
});

Response

{
  "file_id": "report.pdf",
  "name": "report.pdf",
  "type": "pdf",
  "state": "ready",
  "source_id": "src_01139ca8ca59f2556f65b60e",
  "uploaded_at": 1792618822534,
  "pages": 2,
  "ids": ["src_01139ca8ca59f2556f65b60e:report.pdf"],
  "ocr_failed": [],
  "ocr_pending": [],
  "markdown": "<!-- page 1 -->\n\n# Q3 report\n\nRevenue grew 12 percent in EMEA.\n\n<!-- page 2 -->\n\n# Outlook\n\nWe expect Q4 revenue to grow again.",
  "parts": [
    { "locator": { "page": 1 }, "markdown": "# Q3 report\n\nRevenue grew 12 percent in EMEA.", "ocr": true, "confidence": null },
    { "locator": { "page": 2 }, "markdown": "# Outlook\n\nWe expect Q4 revenue to grow again.", "ocr": true, "confidence": null }
  ],
  "without_text": { "pages": [], "slides": [], "images": [] }
}

응답은 파일을 읽을 때까지 최대 wait초 기다립니다. ready 또는 failed이면 200, 아직 읽는 중이면 202를 반환합니다.

옵션

쿼리 파라미터이며, 별도 표기가 없으면 두 라우트 모두에 적용됩니다.

옵션	타입	기능
`name`	string	최대 4,096자의 파일 이름. 확장자로 `.csv`, `.tsv`, `.md`를 텍스트와 구분합니다
`id`	string	업로드 전용. 파일 id로, 문서 id의 끝부분이 됩니다. 기본값은 다른 문자를 `-`로 바꾼 `name`입니다
`type`	string	`pdf`, `docx`, `pptx`, `xlsx`, `csv`, `png`, … (전체). 없으면 바이트, 그다음 이름에서 판단합니다
`user`	string	업로드 전용. 파일 소유자. 사용자를 삭제하면 파일도 삭제됩니다
`metadata`	string	업로드 전용. 문서의 메타데이터에 복사되는 JSON 객체
`pages`	string	읽을 페이지, 슬라이드 또는 프레임. 예: `1-20,25` 또는 `5-`
`password`	string	보호된 PDF, Word, PowerPoint, Excel 파일(최대 20 MiB)을 엽니다
`layout`	boolean, 기본값 `false`	OCR로 읽은 각 부분에 페이지 영역인 `blocks`도 포함됩니다(필드)
`wait`	초, 기본값 60	`202` 전에 읽기를 기다리는 시간, 최대 300. `0`은 즉시 응답합니다

application/pdf 같은 Content-Type으로도 타입을 지정할 수 있습니다.
wait: true는 60입니다. 응답은 항상 105초 이내에 옵니다. 업로드에서 false는 텍스트가 저장되는 즉시 ocr_pending과 함께 응답합니다.
pages 밖의 페이지는 읽거나 OCR하지 않습니다. 페이지가 없는 파일에 pages를 쓰면 400입니다.

전체 스키마: 파일 업로드.

응답

필드	의미
`file_id`, `name`, `type`	사용된 id, 이름, 판별된 타입(모든 이미지 형식은 `image`)
`state`	`queued`, `parsing`, `ocr`(OCR이 아직 `ocr_pending`을 읽는 중), `ready`, 또는 `error`와 함께 `failed`
`source_id`	네임스페이스의 파일 소스. 문서 id가 이것으로 시작합니다
`ids`	`ready`가 되면 파일의 단일 문서 `["<source_id>:<file_id>"]`
`uploaded_at`	Unix 밀리초
`result`	같은 파일, 이름, 메타데이터, 옵션이 이전에 업로드된 경우 `unchanged`. 다시 읽지 않습니다
`pages`	PDF의 페이지 또는 이미지의 프레임
`ocr_failed`	여러 번 시도해도 OCR이 읽지 못한 페이지. 다시 업로드하면 재시도합니다
`markdown`, `parts`, `without_text`	결과

images_without_text, pages_without_text, pages_ocr, images_ocr, sheets, slides, slides_without_text는 지원 중단되었습니다. parts와 without_text가 같은 정보를 제공합니다.

파일 확인

GET /namespaces/:namespace/files/:id 파일의 최신 업로드를 같은 필드로 반환합니다. 202 이후에 폴링하세요.

curl https://api.conare.ai/namespaces/reports/files/report.pdf \
  -H "Authorization: Bearer $CONARE_API_KEY"

const file = await reports.getFile("report.pdf");

옵션	타입	기능
`user`	string	`user`와 함께 업로드한 파일의 사용자

전체 스키마: 파일 읽기.

저장된 문서

파일 하나는 문서 하나, <source_id>:<file_id>입니다. 페이지, 슬라이드, 시트 행, 섹션, 그림은 그 문서의 부분입니다.

어디서	받는 것
검색	PDF나 이미지의 페이지, 슬라이드, 시트의 행 범위는 각각 하나의 결과이며, id는 `<source_id>:<file_id>$<part>`입니다(`$page-3`, `$slide-4`, `$<sheet>-1`)
텍스트, Markdown, Word 파일 검색	결과 하나, 즉 파일 `<source_id>:<file_id>`이며, 파일 어디에서든 나온 구절이 함께 옵니다
결과의 `metadata`	그 부분 또는 첫 구절의 위치. 키는 아래 표와 같습니다
`GET /namespaces/:namespace/documents/:id`	파일 id로는 파일 전체의 텍스트(페이지 사이에 빈 줄), 부분 id로는 그 부분만

부분의 위치

파일	메타데이터의 위치
PDF	`page`
Word, 텍스트, Markdown	`part`, `heading`, 텍스트는 `lines`
PowerPoint	`slide`
Excel, CSV, TSV	`sheet`, `rows`
이미지	`page`, `frame`
Word 안의 그림	`image`, `heading`
슬라이드의 그림	`slide`, `image`
시트의 차트	`sheet`

문서에는 file, file_id, file_type, uploaded_at, 업로드의 metadata도 있으며, OCR로 읽었으면 ocr: true가 있습니다. 이전에 업로드한 파일은 다시 업로드할 때까지 부분마다 문서 하나(<source_id>:<file_id>:page-1 등)로 남아 있을 수 있습니다.

목적	방법
파일 교체	같은 id로 다시 업로드하세요
안전한 재시도	같은 파일, 이름, 메타데이터, 옵션이면 `unchanged`로 응답하며 `Idempotency-Key`가 필요 없습니다
파일 하나 검색	`{ "file_id": "report.pdf" }`로 필터하세요
페이지 하나 검색	`{ "file_id": "report.pdf", "page": 3 }`로 필터하세요
사용자 분리	`user`로 업로드하고 `user`로 검색하세요
원본 삭제	네임스페이스나 해당 사용자가 삭제될 때까지 보관됩니다

파일 파싱

POST /parse 파일을 Markdown으로 반환하고 아무것도 저장하지 않습니다. Models only 키를 포함해 모든 키로 파싱할 수 있습니다.

curl "https://api.conare.ai/parse?name=report.pdf" \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

curl https://api.conare.ai/parse \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/report.pdf"}'

import { readFile } from "node:fs/promises";

const out = await conare.parse(await readFile("report.pdf"), { name: "report.pdf" });
if (out.state === "parsing") console.log(await conare.getParse(out.id));

Response

{
  "id": "prs_76149e8db2be257fa8a0ac01",
  "state": "done",
  "type": "pdf",
  "name": "report.pdf",
  "pages": 2,
  "markdown": "<!-- page 1 -->\n\n# Q3 report\n\nRevenue grew 12 percent in EMEA.\n\n<!-- page 2 -->\n\n# Outlook\n\nWe expect Q4 revenue to grow again.",
  "parts": [
    { "locator": { "page": 1 }, "markdown": "# Q3 report\n\nRevenue grew 12 percent in EMEA.", "ocr": true, "confidence": null },
    { "locator": { "page": 2 }, "markdown": "# Outlook\n\nWe expect Q4 revenue to grow again.", "ocr": true, "confidence": null }
  ],
  "without_text": { "pages": [], "slides": [], "images": [] }
}

옵션	타입	기능
`url`	string	JSON 본문에서: 공개 주소의 `https` URL. 60초 이내에 가져오며 최대 20 MiB
`name`, `type`, `pages`, `password`, `layout`, `wait`		업로드와 같습니다

본문은 최대 20 MiB이며, OCR은 최대 100페이지를 읽습니다. 이후 페이지는 텍스트 레이어를 유지합니다.
JSON 파일을 파싱하려면 text/plain으로 보내세요.

전체 스키마: 파일 파싱.

파싱 결과 가져오기

GET /parse/:id 202(state: "parsing")로 응답한 파싱은 24시간 보관됩니다. state가 done이 되거나 error와 함께 failed가 될 때까지 가져오세요.

curl

curl https://api.conare.ai/parse/prs_0e631c59528ac4f7424dc776 \
  -H "Authorization: Bearer $CONARE_API_KEY"

전체 스키마: 파싱 결과 읽기.

결과

필드	의미
`markdown`	파일 전체. 각 페이지, 슬라이드, 시트는 `<!-- page 3 -->`, `<!-- slide 4 -->` 또는 `<!-- sheet "Q3" -->`로 시작합니다
`parts`	읽기 순서대로, 각각 `locator`, `markdown`, `ocr`, `confidence`를 가집니다
`parts[].locator`	`{"page": 3}`, `{"slide": 4, "image": 1}`, `{"sheet": "Q3", "rows": "2-41"}` 또는 `{"part": 2, "heading": "..."}`
`parts[].ocr`	텍스트 레이어가 아니라 페이지 이미지에서 OCR로 읽음
`parts[].confidence`	OCR의 확신도, 0에서 1. OCR이 값을 주지 않으면 `null`(대부분의 디지털 원본 페이지)
`without_text`	텍스트가 없는 `pages`, `slides`, `images`. 각 그림에는 `reason`이 있습니다

Markdown 규칙은 파일 형식에 있습니다.

오류

오류	발생 시점
`400 invalid_request`	옵션이 유효하지 않음: 페이지가 없는 파일의 `pages`, 300을 넘는 `wait`, JSON 객체가 아닌 `metadata`, 공개 주소의 `https`가 아닌 URL
`400 fetch_failed`	URL이 파일과 함께 `200`으로 응답하지 않음
`404 parse_not_found`	지난 24시간 동안 해당 id로 `202`를 응답한 파싱이 없음
`409 file_replaced`	응답을 기다리는 동안 파일이 삭제됨
`409 user_purging`	사용자가 삭제되는 중
`413 payload_too_large`	512 MiB 초과(업로드) 또는 20 MiB 초과(파싱 또는 `password` 사용 시)
`415 unsupported_file`	지원되지 않는 타입이거나 선언한 `type`과 다름. 메시지에 저장할 형식이 안내됩니다
`422 password_protected`	파일에 비밀번호가 있음: `password`로 보내세요
`422 unreadable_file`	파일이 손상됨
`422 no_text`	텍스트가 있는 페이지, 시트, 슬라이드, 단락, 그림이 없음
`503 files_unavailable`	지금은 파일을 저장할 수 없음. 나중에 다시 시도하세요

5,000개를 넘는 페이지, 시트 또는 슬라이드가 있는 파일은 too_large와 함께 failed로 끝납니다.

시작하기

핵심

파일

동기화

모델

도구

파일

파일 업로드

옵션

응답

파일 확인

저장된 문서

부분의 위치

파일 파싱

파싱 결과 가져오기

결과

오류

​파일 업로드

​옵션

​응답

​파일 확인

​저장된 문서

​부분의 위치

​파일 파싱

​파싱 결과 가져오기

​결과

​오류

파일 업로드

옵션

응답

파일 확인

저장된 문서

부분의 위치

파일 파싱

파싱 결과 가져오기

결과

오류