---
title: "Create or update a custom model"
method: POST
path: "/api/models/"
tags: ["Models"]
---

# Create or update a custom model

`POST /api/models/`

## Request

- Base URL: `https://api.respan.ai`
- URL: `https://api.respan.ai/api/models/`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Create an organization-specific custom model. If a model with the same `model_name` already exists in your organization, it is updated and the endpoint returns `200`.

## Request body

- object
  - `model_name` string, required: Unique model name within your organization.
  - `base_model_name` string: Base model to inherit properties from.
  - `custom_provider_id` string: The custom provider to call the model through. Required unless `base_model_name` is set, in which case the base model's provider is used.
  - `provider_id` string: Alternative to `custom_provider_id`.
  - `input_cost` number: Cost per 1M input tokens in USD.
  - `output_cost` number: Cost per 1M output tokens in USD.
  - `cache_hit_input_cost` number: Cost per 1M cached input tokens in USD.
  - `cache_creation_input_cost` number: Cost per 1M cache creation input tokens in USD.
  - `max_context_window` integer: Maximum context window size.
  - `function_call` 0 | 1
  - `image_support` 0 | 1
  - `supported_params_override` object: Partial override for the model's parameters: a map of parameter name to a parameter definition with the same shape as `supported_params` entries (`name`, `type`, `default`, `range` with `min` and `max`, `description`, `required`), or `null` to remove the parameter. Replaces any earlier override. The response returns the computed `supported_params`.

## Response `200`

Updated existing model.

- object
  - `id` string, required: Model string ID. Same value as `model_name`.
  - `model_name` string, required: Model name used in API calls.
  - `base_model_name` string: Base model inherited from, when configured.
  - `affiliation_category` 'keywordsai' | 'custom': `keywordsai` for built-in models, `custom` for your organization's models.
  - `is_called_by_custom_name` boolean: Whether requests are sent upstream using this custom model name.
  - `input_cost` number: Cost per 1M input tokens in USD.
  - `output_cost` number: Cost per 1M output tokens in USD.
  - `cache_hit_input_cost` number: Cost per 1M cached input tokens in USD.
  - `cache_creation_input_cost` number: Cost per 1M cache creation input tokens in USD.
  - `max_context_window` integer: Maximum context window size.
  - `function_call` 0 | 1: Function/tool calling support. `0` = no, `1` = yes.
  - `image_support` 0 | 1: Vision input support. `0` = no, `1` = yes.
  - `model_type` 'chat' | 'embedding' | 'audio': Model type.
  - `supported_params` object: Computed parameter support after applying model-specific overrides.
  - `provider` object
    - `id` string, required: Provider string ID. Same value as `provider_id`.
    - `provider_id` string, required: Unique provider identifier within your organization.
    - `provider_name` string, required: Human-readable provider name.
    - `extra_kwargs` object: Provider configuration such as `base_url` and timeout values. Secret values are not returned here.
    - `created_at` string, date-time, nullable
    - `updated_at` string, date-time, nullable

## Other responses

- `201`: Created model.
- `400`: Bad Request
- `403`: The API key is missing, invalid or expired, or it doesn't have permission for this action.
- `404`: Not Found

## Changes

- **2026-10-21** `c30bcb383ee8`: 15 breaking, 4 warning, 17 info
  - request body became required
  - removed the enum value `0` of the request property `function_call`
  - removed the enum value `0` of the request property `image_support`
  - removed the enum value `1` of the request property `function_call`
  - …32 more
- **2026-10-02** `b830b79cfd52`: 10 warning, 3 info
  - removed the request property `display_name`
  - removed the request property `streaming_support`
  - removed the optional property `created_at` from the response with the `200` status
  - removed the optional property `display_name` from the response with the `200` status
  - …9 more
- **2026-09-17** `6fa8242da8c2`: 1 warning, 1 info
  - deleted the `header` request parameter `Authorization`
  - the endpoint scheme security `RespanApiKey` was added to the API
- **2026-09-12** `22b868ef3f22`: 1 info
  - api operation id `create-custom-model` removed and replaced with `models_createCustomModel`

[Operation history](https://skmtc.dev/respan/apis/respan-api/changes/api/models/post.md)

---

[API](https://skmtc.dev/respan/apis/respan-api.md) - [All operations](https://skmtc.dev/respan/apis/respan-api/llms.txt) - [OpenAPI document](https://skmtc.dev/respan/apis/respan-api/revisions/900841387635?raw)