Create Custom Model

Create a new custom speech recognition model for domain-specific training.

Endpoint

POST /api/v3/custom_models

Authentication

Requires API key with custom_models:write scope.

Authorization: Bearer YOUR_API_KEY

Request

Headers

Header	Value	Required
Authorization	Bearer YOUR_API_KEY	Yes
Content-Type	application/json	Yes

Request Body

{
  "name": "Medical Cardiology EN",
  "language": "en",
  "base_model": "medical",
  "description": "Custom model for cardiology consultations and reports"
}

Parameters

Parameter	Type	Required	Description	Constraints
name	string	Yes	Model display name	1-200 characters, non-empty
language	string	Yes	Base language code	ISO 639-1 (2 letters), must be supported
base_model	string	No	Base model type	Enum: general, medical, legal, technical (default: general)
description	string	No	Model description	0-1000 characters

Supported Languages

The model's language must match one of Scriptix's supported languages:

• European: en, nl, fr, de, es, it, pt, pl, cs, da, fi, el, hu, no, ro, sk, sv
• Middle East: ar, he, tr, fa
• Asian: zh, ja, ko, hi, th, id, vi
• Other: ru, uk, ms, ta, te

See Supported Languages for complete list.

Base Model Types

Type	Description	Best For
general	General speech, broadest vocabulary	Business, interviews, general transcription
medical	Medical terminology, procedures	Clinical notes, radiology, consultations
legal	Legal vocabulary, case law	Depositions, legal consultations, court
technical	Technical/IT terminology	Tech support, engineering, software dev

Response

Success Response

Status Code: 201 Created

{
  "id": 123,
  "model_key": "custom_model_123",
  "name": "Medical Cardiology EN",
  "description": "Custom model for cardiology consultations and reports",
  "language": "en",
  "base_model": "medical",
  "training_status": 1,
  "status_message": "Model created. Upload training data to begin.",
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:00:00Z"
}

Response Fields

Field	Type	Description
id	integer	Unique model identifier
model_key	string	Internal model key for API usage (format: custom_model_{id})
name	string	Model display name
description	string | null	Model description
language	string	Base language code
base_model	string	Base model type
training_status	integer	Training status (always 1 on creation)
status_message	string	Human-readable status
created_at	string	ISO 8601 creation timestamp
updated_at	string	ISO 8601 last update timestamp

Training Status

New models are created with training_status = 1 (Not Running).

Next steps:

1. Upload training data → Upload Training Data
2. Upload test data → Upload Training Data
3. Start training → Train Model

Error Responses

400 Bad Request - Validation Error

{
  "error": "Validation Error",
  "message": "Invalid field values",
  "details": {
    "name": "Name cannot be empty",
    "language": "Language 'xx' is not supported"
  }
}

Common validation errors:

• Empty or whitespace-only name
• Unsupported language code
• Invalid base_model value
• name exceeds 200 characters
• description exceeds 1000 characters

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

402 Payment Required - Quota Exceeded

{
  "error": "Quota Exceeded",
  "message": "Custom model limit reached for your plan",
  "error_code": "MODEL_LIMIT_EXCEEDED",
  "details": {
    "current_models": 5,
    "plan_limit": 5,
    "plan": "Gold"
  }
}

Plan limits:

• Gold: 5 custom models
• Enterprise: Unlimited

500 Internal Server Error

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred. Please try again."
}

Examples

cURL

curl -X POST https://api.scriptix.io/api/v3/custom_models \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Medical Cardiology EN",
    "language": "en",
    "base_model": "medical",
    "description": "Custom model for cardiology consultations and reports"
  }'

Python

import requests

url = "https://api.scriptix.io/api/v3/custom_models"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "name": "Medical Cardiology EN",
    "language": "en",
    "base_model": "medical",
    "description": "Custom model for cardiology consultations and reports"
}

response = requests.post(url, headers=headers, json=data)
model = response.json()

print(f"Created model ID: {model['id']}")
print(f"Model key: {model['model_key']}")
print(f"Status: {model['status_message']}")

JavaScript (Node.js)

const axios = require('axios');

const createCustomModel = async () => {
  try {
    const response = await axios.post(
      'https://api.scriptix.io/api/v3/custom_models',
      {
        name: 'Medical Cardiology EN',
        language: 'en',
        base_model: 'medical',
        description: 'Custom model for cardiology consultations and reports'
      },
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        }
      }
    );

    const model = response.data;
    console.log('Created model ID:', model.id);
    console.log('Model key:', model.model_key);
    console.log('Status:', model.status_message);

    return model;
  } catch (error) {
    console.error('Error creating model:', error.response.data);
  }
};

createCustomModel();

TypeScript

interface CreateModelRequest {
  name: string;
  language: string;
  base_model?: 'general' | 'medical' | 'legal' | 'technical';
  description?: string;
}

interface CustomModel {
  id: number;
  model_key: string;
  name: string;
  description: string | null;
  language: string;
  base_model: string;
  training_status: number;
  status_message: string;
  created_at: string;
  updated_at: string;
}

const createCustomModel = async (
  data: CreateModelRequest
): Promise<CustomModel> => {
  const response = await fetch('https://api.scriptix.io/api/v3/custom_models', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message);
  }

  return response.json();
};

// Usage
createCustomModel({
  name: 'Medical Cardiology EN',
  language: 'en',
  base_model: 'medical',
  description: 'Custom model for cardiology consultations and reports'
}).then(model => {
  console.log('Created:', model.model_key);
});

Validation Rules

Name

• Required: Yes
• Type: String
• Length: 1-200 characters
• Pattern: Any non-empty string (whitespace-only not allowed)

Examples:

• ✅ "Medical Cardiology EN"
• ✅ "Legal-NL-v2"
• ✅ "Tech Support Model 2025"
• ❌ "" (empty)
• ❌ " " (whitespace only)
• ❌ String > 200 characters

Language

• Required: Yes
• Type: String
• Length: 2 characters
• Pattern: ISO 639-1 lowercase
• Validation: Must be in supported languages list

Examples:

• ✅ "en"
• ✅ "nl"
• ✅ "de"
• ❌ "EN" (uppercase not allowed)
• ❌ "eng" (3-letter codes not supported)
• ❌ "xx" (unsupported language)

Base Model

• Required: No (defaults to "general")
• Type: String
• Enum: general, medical, legal, technical
• Case-sensitive: Yes (lowercase only)

Examples:

• ✅ "medical"
• ✅ "general"
• ✅ Not provided (defaults to "general")
• ❌ "Medical" (capitalized)
• ❌ "healthcare" (not in enum)

Description

• Required: No
• Type: String
• Length: 0-1000 characters
• Nullable: Yes

Examples:

• ✅ "Cardiology model trained on 50+ hours"
• ✅ "" (empty string)
• ✅ Not provided / null
• ❌ String > 1000 characters

Best Practices

Naming Convention

Use clear, descriptive names that include:

• Domain: Medical, Legal, Technical, etc.
• Specialty: Cardiology, Contract Law, Tech Support
• Language: EN, NL, FR, etc.
• Version: v1, v2, 2025, etc. (if maintaining multiple versions)

Examples:

• "Medical Radiology EN v2"
• "Legal Contract NL 2025"
• "Tech Support DE"
• "Sales Calls EN-US"

Descriptions

Include helpful context in descriptions:

• Training data sources
• Intended use case
• Audio hours used
• Special vocabulary covered
• Date created/updated

Example:

"Cardiology model trained on 30 hours of MRI and CT scan report
dictation from 15 physicians. Includes extensive cardiac anatomy
and diagnostic terminology. Created Jan 2025."

Base Model Selection

Choose the base model closest to your domain:

1. Medical terminology? → Use medical
2. Legal vocabulary? → Use legal
3. Technical/IT terms? → Use technical
4. General business/other? → Use general

The closer the base model to your domain, the better your results.

Language Selection

• Model language must match your transcription audio language
• Cannot be changed after creation
• For multilingual use cases, create separate models per language

Rate Limits

• Requests: 10 requests/hour
• Concurrent: 3 concurrent requests

Exceeding limits returns 429 Too Many Requests.

Next Steps

After creating your model:

1. Upload Training Data → Upload Training Data

   • Minimum 5 hours of audio
   • 80% training / 20% test split recommended

2. Start Training → Train Model

   • Training typically takes 6-12 hours
   • Monitor progress via status endpoint

3. Use in Production

   • Reference model_key in transcription requests
   • Test thoroughly before full deployment

Related Endpoints

• List Models - List all your custom models
• Get Model - Retrieve model details
• Update Model - Update name/description
• Delete Model - Delete model
• Upload Training Data - Add training data
• Train Model - Start training

See Also

• Custom Models Overview - Complete guide
• Data Models - Schema reference
• Supported Languages - All supported languages

---

Need help? Contact support@scriptix.io or visit our documentation.