파일 엔드포인트

파일 엔드포인트 (Files Endpoints)

Files API입니다. 파인튜닝·배치·OCR 등 여러 엔드포인트에서 쓸 파일을 업로드하고, 목록·상세·다운로드·서명 URL·삭제를 처리하는 API예요.

출처: 문서

본문

파일을 관리하는 엔드포인트 모음이에요. 파일을 올려두고 ID를 받아 다른 API에서 재사용할 수 있고, 필요할 때 내려받거나 서명된 임시 URL로 공유할 수 있답니다.

GET /v1/files — List Files (파일 목록 조회)

사용자 조직에 속한 파일 목록을 반환합니다.

응답 필드 (200 OK):

data#array<FileSchema> (필수) — 파일 목록.
object#string (필수)
total#integer|null

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.files.list({});

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.files.list(page=0, page_size=100, include_total=True)

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/files \
 -X GET \
 -H 'Authorization: Bearer ***'

응답 예시 (200):

{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f09",
      "object": "file",
      "bytes": 13000,
      "created_at": 1716963433,
      "filename": "files_upload.jsonl",
      "purpose": "batch",
      "sample_type": "batch_result",
      "source": "mistral",
      "num_lines": 2,
      "mimetype": "application/jsonl",
      "signature": null
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "object": "file",
      "bytes": 9000,
      "created_at": 1716963500,
      "filename": "fine_tune.jsonl",
      "purpose": "fine-tune",
      "sample_type": "pretrain",
      "source": "upload",
      "num_lines": 10,
      "mimetype": "application/jsonl",
      "signature": null
    }
  ],
  "total": 2
}

POST /v1/files — Upload File (파일 업로드)

여러 엔드포인트에서 쓸 수 있는 파일을 업로드합니다.

개별 파일 크기는 최대 512MB까지 가능해요. Fine-tuning API는 .jsonl 파일만 지원합니다. 저장 한도를 늘려야 한다면 문의해 주세요.

요청 본문 (multipart/form-data):

file#File (필수) — 업로드할 파일. 커스텀 파일명을 쓰려면 file=@path/to/your/file.jsonl;filename=custom_name.jsonl, 아니면 file=@path/to/your/file.jsonl 형태로 보내면 돼요.
purpose#"fine-tune"|"batch"|"ocr" — 파일 용도.
visibility#"workspace"|"user" — 기본값 "workspace". 공개 범위.
expiry#integer|null — 만료 시각.

응답 필드 (200 OK):

id#string (필수) — 파일의 고유 ID.
object#string (필수) — 항상 "file".
bytes#integer (필수) — 파일 크기(바이트).
created_at#integer (필수) — 이벤트의 UNIX 타임스탬프(초).
expires_at#integer|null
filename#string (필수) — 업로드된 파일명.
purpose#"fine-tune"|"batch"|"ocr" (필수)
sample_type#"pretrain"|"instruct"|"batch_request"|"batch_result"|"batch_error" (필수)
source#"upload"|"repository"|"mistral" (필수)
num_lines#integer|null
mimetype#string|null
signature#string|null
visibility#"workspace"|"user"

TypeScript:

import { Mistral } from "@mistralai/mistralai";
import { openAsBlob } from "node:fs";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.files.upload({
    file: await openAsBlob("example.file"),
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.files.upload(file={
        "file_name": "example.file",
        "content": open("example.file", "rb"),
    }, visibility="workspace")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/files \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{
  "file": {
    "content": "ipsum eiusmod",
    "fileName": "consequat do"
  }
}'

응답 예시 (200):

{
  "id": "e85980c9-409e-4a46-9304-36588f6292b0",
  "object": "file",
  "bytes": null,
  "created_at": 1759500189,
  "filename": "example.file.jsonl",
  "purpose": "fine-tune",
  "sample_type": "instruct",
  "source": "upload",
  "num_lines": 2,
  "mimetype": "application/jsonl",
  "signature": "d4821d2de1917341"
}

GET /v1/files/{file_id} — Retrieve File (파일 조회)

특정 파일에 대한 정보를 반환합니다.

경로 파라미터:

file_id#string (필수)

응답 필드 (200 OK):

id#string (필수), object#string (필수), bytes#integer (필수), created_at#integer (필수), deleted#boolean (필수), filename#string (필수), purpose#"fine-tune"|"batch"|"ocr" (필수), sample_type#"pretrain"|"instruct"|"batch_request"|"batch_result"|"batch_error" (필수), source#"upload"|"repository"|"mistral" (필수), expires_at#integer|null, num_lines#integer|null, mimetype#string|null, signature#string|null, visibility#"workspace"|"user"

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.files.retrieve({
    fileId: "f2a27685-ca4e-4dc2-9f2b-88c422c3e0f6",
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.files.retrieve(file_id="f2a27685-ca4e-4dc2-9f2b-88c422c3e0f6")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/files/{file_id} \
 -X GET \
 -H 'Authorization: Bearer ***'

응답 예시 (200):

{
  "id": "e85980c9-409e-4a46-9304-36588f6292b0",
  "object": "file",
  "bytes": null,
  "created_at": 1759500189,
  "filename": "example.file.jsonl",
  "purpose": "fine-tune",
  "sample_type": "instruct",
  "source": "upload",
  "deleted": false,
  "num_lines": 2,
  "mimetype": "application/jsonl",
  "signature": "d4821d2de1917341"
}

DELETE /v1/files/{file_id} — Delete File (파일 삭제)

파일을 삭제합니다.

경로 파라미터:

file_id#string (필수)

응답 필드 (200 OK):

deleted#boolean (필수) — 삭제 상태.
id#string (필수) — 삭제된 파일의 ID.
object#string (필수) — 삭제된 객체의 타입.

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.files.delete({
    fileId: "3b6d45eb-e30b-416f-8019-f47e2e93d930",
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.files.delete(file_id="3b6d45eb-e30b-416f-8019-f47e2e93d930")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/files/{file_id} \
 -X DELETE \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json'

응답 예시 (200):

{
  "id": "e85980c9-409e-4a46-9304-36588f6292b0",
  "object": "file",
  "deleted": true
}

GET /v1/files/{file_id}/content — Download File (파일 다운로드)

파일을 다운로드합니다.

경로 파라미터:

file_id#string (필수)

응답 (200): 타입 binary — 파일 바이너리.

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.files.download({
    fileId: "f8919994-a4a1-46b2-8b5b-06335a4300ce",
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.files.download(file_id="f8919994-a4a1-46b2-8b5b-06335a4300ce")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/files/{file_id}/content \
 -X GET \
 -H 'Authorization: Bearer ***'

응답 예시 (200):

"base64-encoded-data"

GET /v1/files/{file_id}/url — Get Signed Url (서명 URL 발급)

파일을 가리키는 서명된 URL을 가져옵니다.

경로/쿼리 파라미터:

file_id#string (필수)
expiry#integer — URL이 유효한 시간(시간 단위). 기본 24시간, 1~168시간 사이여야 해요.

응답 필드 (200 OK):

url#string (필수)

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.files.getSignedUrl({
    fileId: "06a020ab-355c-49a6-b19d-304b7c01699f",
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.files.get_signed_url(file_id="06a020ab-355c-49a6-b19d-304b7c01699f", expiry=24)

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/files/{file_id}/url \
 -X GET \
 -H 'Authorization: Bearer ***'

응답 예시 (200):

{
  "url": "https://mistralaifilesapiprodswe.blob.core.windows.net/fine-tune/.../.../e85980c9409e4a46930436588f6292b0.jsonl?se=2025-10-04T14%3A16%3A17Z&sp=r&sv=2025-01-05&sr=b&sig=..."
}

더 알아보기 (Learn more)

Files Endpoints — 공식 API 문서
Fine-tuning — 파인튜닝 안내