배치 엔드포인트

배치 엔드포인트 (Batch Endpoints)

Batch API입니다. 대량의 요청을 한 번에 제출해 비동기로 처리하는 배치 잡(job)을 만들고, 조회·취소·삭제하는 방법을 다룹니다.

출처: 문서

본문

배치 추론을 위한 엔드포인트 모음이에요. 수천 건의 요청을 .jsonl 파일에 담아 제출하면 큐에 쌓였다가 순서대로 처리되고, 상태를 조회하거나 취소·삭제할 수 있답니다.

GET /v1/batch/jobs — Get Batch Jobs (배치 잡 목록 조회)

조직과 사용자에 대한 배치 잡 목록을 가져옵니다.

응답 필드 (200 OK):

  • data#array<BatchJob> — 배치 잡 목록.
  • object#string — 기본값 "list".
  • total#integer (필수) — 전체 잡 수.

TypeScript:

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

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

async function run() {
  const result = await mistral.batch.jobs.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.batch.jobs.list(page=0, page_size=100, created_by_me=False, order_by="-created")

    # Handle response
    print(res)

curl:

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

응답 예시 (200):

{
  "total": 87
}

POST /v1/batch/jobs — Create Batch Job (배치 잡 생성)

새 배치 잡을 만들면 처리 대기 큐에 들어갑니다.

요청 본문:

  • endpoint#"/v1/chat/completions"|"/v1/embeddings"|"/v1/fim/completions"|"/v1/moderations"|"/v1/chat/moderations"|"/v1/ocr"|"/v1/classifications"|"/v1/chat/classifications"|"/v1/conversations"|"/v1/audio/transcriptions" (필수) — 배치로 보낼 대상 엔드포인트.
  • input_files#array<string>|null — 배치 추론용 .jsonl 파일 목록. 각 줄은 body 필드에 요청 페이로드를 담은 JSON 객체여야 해요:
{"custom_id": "0", "body": {"max_tokens": 100, "messages": [{"role": "user", "content": "What is the best French cheese?"}]}}
{"custom_id": "1", "body": {"max_tokens": 100, "messages": [{"role": "user", "content": "What is the best French wine?"}]}}
  • model#string|null — 배치 추론에 사용할 모델.
  • agent_id#string|null — deprecated agents api의 특정 에이전트를 배치 추론에 쓰고 싶다면 여기에 에이전트 ID를 지정할 수 있어요.
  • metadata#map<string>|null — 배치 잡과 연결할 임의 메타데이터.
  • requests#array<BatchRequest>|null — 요청 목록.
  • timeout_hours#integer — 기본값 24. 배치 잡의 타임아웃(시간 단위).

응답 필드 (200 OK):

  • id#string (필수)
  • object#string — 기본값 "batch".
  • endpoint#string (필수)
  • model#string|null
  • agent_id#string|null
  • created_at#integer (필수)
  • started_at#integer|null
  • completed_at#integer|null
  • status#"QUEUED"|"RUNNING"|"SUCCESS"|"FAILED"|"TIMEOUT_EXCEEDED"|"CANCELLATION_REQUESTED"|"CANCELLED" (필수)
  • total_requests#integer (필수)
  • completed_requests#integer (필수)
  • succeeded_requests#integer (필수)
  • failed_requests#integer (필수)
  • input_files#array<string> (필수)
  • output_file#string|null
  • error_file#string|null
  • errors#array<BatchError> (필수)
  • outputs#array<map<any>>|null
  • metadata#map<any>|null

TypeScript:

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

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

async function run() {
  const result = await mistral.batch.jobs.create({
    endpoint: "/v1/moderations",
    model: "mistral-small-latest",
  });

  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.batch.jobs.create(endpoint="/v1/moderations", model="mistral-small-latest", timeout_hours=24)

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/batch/jobs \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{
  "endpoint": "/v1/chat/completions"
}'

응답 예시 (200):

{
  "completed_requests": "10",
  "created_at": 14,
  "endpoint": "/v1/chat/completions",
  "errors": [
    {
      "message": "Example message."
    }
  ],
  "failed_requests": "0",
  "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "input_files": [
    "019b2bd7-96e7-7219-8c0b-45a73da50088"
  ],
  "status": "QUEUED",
  "succeeded_requests": "10",
  "total_requests": "10"
}

GET /v1/batch/jobs/{job_id} — Get Batch Job (배치 잡 조회)

UUID로 배치 잡의 상세 정보를 가져옵니다.

경로 파라미터:

  • job_id#string (필수)

쿼리 파라미터:

  • inline#boolean|null — true면 결과를 응답에 인라인으로 반환해요.

응답 필드 (200 OK): 생성 응답과 동일한 BatchJob 필드 목록입니다.

TypeScript:

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

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

async function run() {
  const result = await mistral.batch.jobs.get({
    jobId: "4017dc9f-b629-42f4-9700-8c681b9e7f0f",
  });

  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.batch.jobs.get(job_id="4017dc9f-b629-42f4-9700-8c681b9e7f0f")

    # Handle response
    print(res)

curl:

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

응답 예시 (200):

{
  "completed_requests": "10",
  "created_at": 14,
  "endpoint": "/v1/chat/completions",
  "errors": [
    {
      "message": "Example message."
    }
  ],
  "failed_requests": "0",
  "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "input_files": [
    "019b2bd7-96e7-7219-8c0b-45a73da50088"
  ],
  "status": "QUEUED",
  "succeeded_requests": "10",
  "total_requests": "10"
}

DELETE /v1/batch/jobs/{job_id} — Delete Batch Job (배치 잡 삭제)

배치 잡 삭제를 요청합니다.

경로 파라미터:

  • job_id#string (필수)

응답 필드 (200 OK):

  • deleted#boolean — 기본값 true.
  • id#string (필수)
  • object#string — 기본값 "batch".

TypeScript:

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

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

async function run() {
  const result = await mistral.batch.jobs.delete({
    jobId: "d9e71426-5791-49ad-b8d1-cf0d90d1b7d0",
  });

  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.batch.jobs.delete(job_id="d9e71426-5791-49ad-b8d1-cf0d90d1b7d0")

    # Handle response
    print(res)

curl:

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

응답 예시 (200):

{
  "id": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}

POST /v1/batch/jobs/{job_id}/cancel — Cancel Batch Job (배치 잡 취소)

배치 잡의 취소를 요청합니다.

경로 파라미터:

  • job_id#string (필수)

응답 필드 (200 OK): BatchJob 필드 목록처럼 status가 CANCELLATION_REQUESTED/CANCELLED로 바뀝니다.

TypeScript:

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

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

async function run() {
  const result = await mistral.batch.jobs.cancel({
    jobId: "4fb29d1c-535b-4f0a-a1cb-2167f86da569",
  });

  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.batch.jobs.cancel(job_id="4fb29d1c-535b-4f0a-a1cb-2167f86da569")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/batch/jobs/{job_id}/cancel \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json'

응답 예시 (200):

{
  "completed_requests": "10",
  "created_at": 14,
  "endpoint": "/v1/chat/completions",
  "errors": [
    {
      "message": "Example message."
    }
  ],
  "failed_requests": "0",
  "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "input_files": [
    "019b2bd7-96e7-7219-8c0b-45a73da50088"
  ],
  "status": "QUEUED",
  "succeeded_requests": "10",
  "total_requests": "10"
}

더 알아보기 (Learn more)