---
title: "Create training job"
method: POST
path: "/v1/training/jobs"
---

# Create training job

`POST /v1/training/jobs`

## Request

- Base URL: `https://api.clichefactory.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.clichefactory.com/v1/training/jobs`
- Auth: none declared

Create a training job.

Optional ``Idempotency-Key`` header makes worker-crash retries safe:
re-submitting the same key with the same body replays the cached
202 response with ``Idempotent-Replayed: true`` instead of starting
a duplicate (billable) training job. TTL is 7 days — long enough to
cover queued jobs that legitimately wait through a workday for
capacity. See README's *Idempotency* section for behaviour details.

## Headers

- `Idempotency-Key` string, nullable
- `X-API-KEY` string, nullable

## Request body

- CreateTrainingJobRequest
  - `request_id` string, required
  - `tenant_id` string, required
  - `project_id` string, required
  - `task_id` string
  - `name` string, nullable
  - `payload` TrainingJobPayload
    - `dataset` DatasetPayload
      - `input_uri` string
      - `ground_truth_uri` string
      - `input_mode` 'markdown' | 'media'
    - `schema` SchemaPayload
      - `name` string, nullable
      - `schema` object
    - `model_schema` SchemaPayload
      - `name` string, nullable
      - `schema` object
    - `model` ModelPayload
      - `provider_model` string, nullable
      - `api_key` string, nullable
      - `max_tokens` integer, nullable
      - `temperature` number, nullable
      - `num_retries` integer, nullable
      - `api_base` string, nullable
      - `ocr_provider_model` string, nullable
      - `ocr_api_key` string, nullable
      - `ocr_max_tokens` integer, nullable
      - `ocr_temperature` number, nullable
      - `trainer_provider_model` string, nullable
      - `trainer_api_key` string, nullable
      - `trainer_max_tokens` integer, nullable
      - `trainer_temperature` number, nullable
      - `extraction` ModelEndpointPayload
        - `provider_model` string, nullable
        - `api_key` string, nullable
        - `max_tokens` integer, nullable
        - `temperature` number, nullable
        - `num_retries` integer, nullable
        - `api_base` string, nullable
      - `ocr` ModelEndpointPayload
        - `provider_model` string, nullable
        - `api_key` string, nullable
        - `max_tokens` integer, nullable
        - `temperature` number, nullable
        - `num_retries` integer, nullable
        - `api_base` string, nullable
      - `trainer` ModelEndpointPayload
        - `provider_model` string, nullable
        - `api_key` string, nullable
        - `max_tokens` integer, nullable
        - `temperature` number, nullable
        - `num_retries` integer, nullable
        - `api_base` string, nullable
    - `parsing` ParsingPayload
      - `input_mode` 'markdown' | 'media', nullable
      - `pdf_image_parser` 'docling' | 'docling_vlm' | 'ocr_llm' | 'yolo_per_partes', nullable
      - `pdf_fallback_to_ocr_llm` boolean, nullable
      - `pdf_structured_fallback_to_image` boolean, nullable
      - `pdf_ocr_engine` 'tesseract' | 'rapidocr' | 'easyocr', nullable
      - `pdf_ocr_lang` string, nullable
      - `use_ocr_llm_body` boolean, nullable
      - `image_parser` 'pytesseract' | 'rapidocr' | 'docling' | 'ocr_llm', nullable
      - `image_parser_fallback` boolean, nullable
      - `image_parser_lang` string, nullable
    - `training` TrainingPayload
      - `optimizer` 'auto' | 'mipro' | 'gepa', nullable
      - `metric` 'exact' | 'fuzzy', nullable
      - `metric_scope` 'aggregate' | 'per_field', nullable
      - `metric_kind` 'graduated_pydantic' | 'graduated_pydantic_item' | 'graduated_pydantic_fuzzy' | 'graduated_pydantic_fuzzy_item', nullable
      - `verifier_enabled` boolean, nullable
      - `dev_split` number, nullable
      - `llm_max_tokens` integer, nullable
      - `llm_temperature` number, nullable
      - `llm_num_retries` integer, nullable
      - `trainer_model_max_tokens` integer, nullable
      - `trainer_model_temperature` number, nullable
    - `tracking` TrackingPayload
      - `experiment_name` string, nullable
    - `trained_module_path` string, nullable
    - `artifact_uri` string, nullable
    - `model_name` string, nullable
    - `llm_model_name` string, nullable
    - `llm_api_key` string, nullable
    - `llm_max_tokens` integer, nullable
    - `llm_temperature` number, nullable
    - `llm_num_retries` integer, nullable
    - `ocr_llm_model_name` string, nullable
    - `ocr_llm_api_key` string, nullable
    - `ocr_model_name` string, nullable
    - `ocr_api_key` string, nullable

## Response `202`

Successful Response

- CreateTrainingJobResponse
  - `job_id` string, required
  - `status` string, required
  - `created_at` string, date-time, required
  - `links` object

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/clichefactory/apis/aio-server.md) · [All operations](https://skmtc.dev/clichefactory/apis/aio-server/llms.txt) · [OpenAPI document](https://skmtc.dev/clichefactory/apis/aio-server/revisions/9bd59f9bbb31?raw)