> ## Documentation Index > Fetch the complete documentation index at: https://docs.omnia-voice.com/llms.txt > Use this file to discover all available pages before exploring further. # Create fine-tuning job > Start a fine-tuning job. Requires an owner/admin key. Billing is per trained token, charged once on completion. ## OpenAPI ````yaml /openapi.json post /v1/fine_tuning/jobs openapi: 3.1.0 info: title: Omnia Management API description: >- The management API behind the improvement loop: capture and setup, request logs and datasets, grades (labels), judges (criteria), evals and deploy gates, fine-tuning and reinforcement learning, dedicated GPU endpoints, and model aliases and versions. Authenticated with a workspace API key (sk_sovereign_...). The inference API (chat, embeddings, rerank, responses) is OpenAI-compatible and documented separately. Responses are snake_case, list endpoints on the loop products use the {"object": "list", "data": [...]} envelope, and refusals use the same nested error shape the gateway emits: {"error": {"message", "type", "code"}}. Request bodies on the loop products (logs, labels, criteria, evals, datasets, aliases) are snake_case; the training and infrastructure products (fine-tuning, GRPO, environment tools, dedicated, model-version adoption) validate camelCase bodies, and each schema below says which it is. Endpoints that spend money require a key minted by a workspace owner or admin and return 403 otherwise. version: 1.0.0 servers: - url: https://gateway.omnia-voice.com description: Production - url: https://platform.omnia-voice.com/api description: Production (legacy alias — same API, older base URL) security: - bearerAuth: [] paths: /v1/fine_tuning/jobs: post: tags: - Fine-tuning summary: Create fine-tuning job description: >- Start a fine-tuning job. Requires an owner/admin key. Billing is per trained token, charged once on completion. operationId: createFineTuningJob requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateFineTuningJob' responses: '201': description: The created job. content: application/json: schema: $ref: '#/components/schemas/FineTuningJob' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/InsufficientBalance' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' components: schemas: CreateFineTuningJob: type: object description: >- This body is camelCase (baseModel, trainingFileId, providerDatasetId), unlike the snake_case loop endpoints; hyperparameter keys inside are snake_case. Training data is required: pass training or the legacy trainingFileId. required: - baseModel properties: baseModel: type: string description: A model id from the fine-tunable catalog. training: type: object description: >- Training data source. Either {kind: "dataset", providerDatasetId, mapping, version?} or {kind: "file", fileId}. properties: kind: type: string description: >- "dataset" (a managed dataset plus a column mapping) or "file" (an uploaded training file). enum: - dataset - file providerDatasetId: type: string description: 'kind dataset: the dataset id to convert into a training file.' version: type: string description: 'kind dataset: optional dataset version.' mapping: type: object description: >- How dataset columns map onto the training schema. Column refs look like {"type": "column", "name": "question"}. properties: type: type: string description: >- One of the four dataset-to-training mappings: text (one text column), prompts (prompt + completion columns), messages (a chat-messages column), pretokenized (input_ids + optional labels / attention_mask). enum: - text - prompts - messages - pretokenized text: type: object required: - type - name properties: type: type: string enum: - column name: type: string prompt: type: object required: - type - name properties: type: type: string enum: - column name: type: string completion: type: object required: - type - name properties: type: type: string enum: - column name: type: string messages: type: object required: - type - name properties: type: type: string enum: - column name: type: string input_ids: type: object required: - type - name properties: type: type: string enum: - column name: type: string labels: type: object required: - type - name properties: type: type: string enum: - column name: type: string attention_mask: type: object required: - type - name properties: type: type: string enum: - column name: type: string fileId: type: string description: 'kind file: an uploaded file''s provider_file_id.' validation: type: object description: Optional validation source, same shape as training. trainingFileId: type: string description: Legacy direct file id (a provider_file_id). Prefer training. validationFileId: type: string description: Legacy validation file id. name: type: string maxLength: 300 suffix: type: string description: A label appended to the resulting model name. maxLength: 120 seed: type: integer description: For reproducibility. minimum: 0 maximum: 2147483647 method: type: string description: >- supervised = SFT/LoRA. spec-draft = a speculative-decoding drafter for a model you serve on a dedicated endpoint. enum: - supervised - spec-draft default: supervised hyperparameters: type: object description: >- Supervised hyperparameters. All optional; keys are snake_case inside this object. Wizard defaults: epochs 3, batch 8, lr 1e-5, ctx 8192, LoRA r/alpha 8. Out-of-bounds values fail with a named field before any money gate runs. properties: n_epochs: type: integer minimum: 1 maximum: 100 learning_rate: type: number description: Exclusive minimum 0, maximum 1. batch_size: type: integer minimum: 1 maximum: 1024 context_length: type: integer minimum: 128 maximum: 262144 warmup_ratio: type: number minimum: 0 maximum: 1 weight_decay: type: number minimum: 0 maximum: 1 packing: type: boolean max_grad_norm: type: number description: Exclusive minimum 0, maximum 1000. lora: type: boolean description: Train a LoRA adapter instead of full weights. lora_r: type: integer minimum: 1 maximum: 512 lora_alpha: type: integer minimum: 1 maximum: 1024 lora_dropout: type: number minimum: 0 maximum: 1 specDraftHyperparameters: type: object description: >- Spec-draft hyperparameters (method spec-draft). Shares the common bounds; adds architecture, num_decoding_heads, loss. properties: n_epochs: type: integer minimum: 1 maximum: 100 learning_rate: type: number batch_size: type: integer minimum: 1 maximum: 1024 context_length: type: integer minimum: 128 maximum: 262144 architecture: type: string maxLength: 200 num_decoding_heads: type: integer minimum: 1 maximum: 16 loss: type: string maxLength: 100 integrations: type: array description: >- Only wandb and hf are supported; anything else is rejected rather than forwarded with someone's credentials. Shapes: {type: "wandb", wandb: {project, api_key, name?, entity?, tags?}} and {type: "hf", hf: {output_repo_name, api_token}}. maxItems: 10 FineTuningJob: type: object properties: id: type: string provider_job_id: type: string description: Opaque upstream job id. name: type: - string - 'null' base_model: type: string method: type: string enum: - supervised - spec-draft status: type: string enum: - VALIDATING_FILES - QUEUED - RUNNING - SUCCEEDED - FAILED - CANCELLED fine_tuned_model: type: - string - 'null' description: Output model id once the job succeeds. deployed_model_name: type: - string - 'null' description: The servable model name after deployment; null until deployed. deploy_status: type: - string - 'null' description: >- Deploy pipeline progress ("queued", "staging", "relaying", "converting", "provisioning", "serving", "failed"); null = never deployed. Stages evolve with the pipeline. deploy_error: type: - string - 'null' description: Failure reason when deploy_status is "failed". trained_tokens: type: - string - 'null' description: Tokens trained, as a string (drives billing). trained_steps: type: - integer - 'null' total_steps: type: - integer - 'null' rate_per_m_token_usd: type: number description: Your price per 1M trained tokens. billed_cost_usd: type: - number - 'null' description: Final billed training cost once the job reaches a terminal status. error: type: - string - 'null' description: Failure reason when status is FAILED. created_at: type: string Error: type: object properties: error: type: object properties: message: type: string type: type: string description: >- invalid_request_error, insufficient_quota, rate_limit_error, or api_error. code: type: string description: >- Machine-stable cause, e.g. invalid_api_key, not_found, insufficient_permissions, precondition_failed. required: - message - type - code description: >- Every refusal — gateway and management API alike — uses this one envelope. responses: BadRequest: description: Malformed request or invalid field. content: application/json: schema: $ref: '#/components/schemas/Error' InsufficientBalance: description: Your wallet can't cover the required prepaid runway. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: message: >- Insufficient balance: deploying this endpoint requires at least 1h of runway. Top up and try again. type: insufficient_quota code: insufficient_balance Forbidden: description: The key lacks the required owner/admin permission. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: >- Abuse guard tripped on a money-creating endpoint (default 20 requests per 60s per workspace). The body is a flat {"error", "type": "rate_limit_error"} object and the Retry-After header says when to retry. content: application/json: schema: type: object properties: error: type: string type: type: string securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your workspace API key, e.g. `sk_sovereign_...`, sent as `Authorization: Bearer `. ````