diff --git a/api.oas3.yaml b/api.oas3.yaml
index c59aa4c..4c8de72 100644
--- a/api.oas3.yaml
+++ b/api.oas3.yaml
@@ -98,6 +98,12 @@ paths:
/generate/{id}:
$ref: "./paths/generateid.yaml"
+ /models:
+ $ref: "./paths/models.yaml"
+
+ /models/{id}:
+ $ref: "./paths/modelsid.yaml"
+
/assets/{id}:
$ref: "./paths/assetsid.yaml"
diff --git a/paths/models.yaml b/paths/models.yaml
new file mode 100644
index 0000000..1782a86
--- /dev/null
+++ b/paths/models.yaml
@@ -0,0 +1,38 @@
+ get:
+ description: |
+ List the generation models available for `prompt`-bearing image, video and audio
+ assets, with the options each accepts and what it costs in credits.
+
+ Use this to populate a model picker and render its option fields, rather than
+ hard coding a model list. A newly launched model appears here without any change
+ on your side. Each entry carries the asset type it generates, so filter the list
+ client side when a picker only needs one kind.
+
+ Option schemas are omitted by default. Request them with `expand=options`.
+
+ **Base URL:** https://api.shotstack.io/edit/{version}
+ summary: List Generation Models
+ operationId: getModels
+ responses:
+ "200":
+ description: The available generation models.
+ content:
+ application/json:
+ schema:
+ $ref: "../schemas/responses/generationmodellistresponse.yaml#/GenerationModelListResponse"
+ security:
+ - DeveloperKey: []
+ tags:
+ - Edit
+ parameters:
+ - in: query
+ name: expand
+ required: false
+ description: >-
+ Set to `options` to include each model's option schema in the list. Omitted by
+ default to keep the response small.
+ schema:
+ type: string
+ enum:
+ - options
+ example: options
diff --git a/paths/modelsid.yaml b/paths/modelsid.yaml
new file mode 100644
index 0000000..a362e46
--- /dev/null
+++ b/paths/modelsid.yaml
@@ -0,0 +1,29 @@
+ get:
+ description: |
+ Get one generation model, including the JSON Schema for the options it accepts and
+ what it costs in credits.
+
+ **Base URL:** https://api.shotstack.io/edit/{version}
+ summary: Get Generation Model
+ operationId: getModel
+ responses:
+ "200":
+ description: The generation model, with its option schema.
+ content:
+ application/json:
+ schema:
+ $ref: "../schemas/generationmodel.yaml#/GenerationModel"
+ "404":
+ description: No model exists with that identifier.
+ security:
+ - DeveloperKey: []
+ tags:
+ - Edit
+ parameters:
+ - in: path
+ name: id
+ required: true
+ description: The model identifier, as returned by the list endpoint.
+ schema:
+ type: string
+ example: seedance-2.0
diff --git a/schemas/generationmodel.yaml b/schemas/generationmodel.yaml
new file mode 100644
index 0000000..9d0bf79
--- /dev/null
+++ b/schemas/generationmodel.yaml
@@ -0,0 +1,35 @@
+ GenerationModel:
+ description: >-
+ A generation model available to `prompt`-bearing image, video and audio assets,
+ with the options it accepts and what it costs. Render a model picker and its
+ option fields from this rather than hard coding a model list, so a newly launched
+ model is available without a client release.
+ properties:
+ model:
+ description: >-
+ The identifier to set as the asset `model`. Carries no provider name, so
+ routing can change without a public rename.
+ type: string
+ example: seedance-2.0
+ type:
+ description: The asset type this model generates.
+ type: string
+ enum:
+ - image
+ - video
+ - audio
+ example: video
+ pricing:
+ description: What one generation with this model costs.
+ $ref: "./generationmodelpricing.yaml#/GenerationModelPricing"
+ options:
+ description: >-
+ JSON Schema for the model's `options` object. Only returned for a single
+ model, or for a list requested with `expand=options`. Values outside this
+ schema are rejected.
+ type: object
+ additionalProperties: true
+ required:
+ - model
+ - type
+ type: object
diff --git a/schemas/generationmodelpricing.yaml b/schemas/generationmodelpricing.yaml
new file mode 100644
index 0000000..0c9c7d0
--- /dev/null
+++ b/schemas/generationmodelpricing.yaml
@@ -0,0 +1,56 @@
+ GenerationModelPricing:
+ description: >-
+ What one generation costs, in credits. There is no formula to evaluate: multiply
+ the rate by the number of units the generation consumes. Where a model charges
+ differently per option value, `credits` is an object keyed by that value and
+ `tieredBy` names the option that selects it.
+ properties:
+ unit:
+ description: >-
+ What one unit is. `render` means the whole generation counts as one unit,
+ whatever its size.
+ type: string
+ enum:
+ - render
+ - second
+ - minute
+ - thousandCharacters
+ example: second
+ credits:
+ description: >-
+ Credits per unit. A number when the rate is flat, or an object keyed by the
+ values of the options named in `tieredBy`.
+ oneOf:
+ - type: number
+ - type: object
+ additionalProperties: true
+ example:
+ 480p: 0.9375
+ 720p: 1.8962
+ 1080p: 4.2625
+ tieredBy:
+ description: >-
+ The options whose values select the rate, outermost first. Absent when
+ `credits` is a single number.
+ type: array
+ items:
+ type: string
+ example:
+ - resolution
+ minUnits:
+ description: >-
+ The fewest units a generation is charged for, when a model has a minimum
+ charge.
+ type: number
+ example: 0.1
+ effectiveFrom:
+ description: >-
+ The date this rate took effect, or `legacy` for a rate that predates dated
+ pricing.
+ type: string
+ example: "2026-08-13"
+ required:
+ - unit
+ - credits
+ - effectiveFrom
+ type: object
diff --git a/schemas/responses/generationmodellistresponse.yaml b/schemas/responses/generationmodellistresponse.yaml
new file mode 100644
index 0000000..bc635ec
--- /dev/null
+++ b/schemas/responses/generationmodellistresponse.yaml
@@ -0,0 +1,11 @@
+ GenerationModelListResponse:
+ description: The generation models available to this account.
+ properties:
+ models:
+ description: The available models.
+ type: array
+ items:
+ $ref: "../generationmodel.yaml#/GenerationModel"
+ required:
+ - models
+ type: object