From d4a86467b293b7bb6f9241aa85810d427ddf835c Mon Sep 17 00:00:00 2001 From: dazzatronus Date: Fri, 21 Aug 2026 10:26:43 +1000 Subject: [PATCH 1/3] docs: document the generation model catalogue endpoints --- api.oas3.yaml | 6 ++ paths/models.yaml | 61 +++++++++++++++++++ paths/modelsid.yaml | 29 +++++++++ schemas/generationmodel.yaml | 47 ++++++++++++++ schemas/generationmodelpricing.yaml | 56 +++++++++++++++++ .../generationmodellistresponse.yaml | 13 ++++ 6 files changed, 212 insertions(+) create mode 100644 paths/models.yaml create mode 100644 paths/modelsid.yaml create mode 100644 schemas/generationmodel.yaml create mode 100644 schemas/generationmodelpricing.yaml create mode 100644 schemas/responses/generationmodellistresponse.yaml 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..af635a9 --- /dev/null +++ b/paths/models.yaml @@ -0,0 +1,61 @@ + 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. + + 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" + "400": + description: An unknown `type` or `status` was supplied. + security: + - DeveloperKey: [] + tags: + - Edit + parameters: + - in: query + name: type + required: false + description: Return only models generating this asset type. + schema: + type: string + enum: + - image + - video + - audio + example: video + - in: query + name: status + required: false + description: Return only models with this lifecycle status. + schema: + type: string + enum: + - active + - experimental + - deprecated + example: active + - 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..da17d61 --- /dev/null +++ b/schemas/generationmodel.yaml @@ -0,0 +1,47 @@ + 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 + status: + description: >- + `active` for a model in general use, `experimental` for one that may change, + and `deprecated` for one scheduled for removal. Warn before a deprecated + model disappears. + type: string + enum: + - active + - experimental + - deprecated + example: active + 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 + - status + 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..eced5be --- /dev/null +++ b/schemas/responses/generationmodellistresponse.yaml @@ -0,0 +1,13 @@ + GenerationModelListResponse: + description: The generation models available to this account. + properties: + models: + description: >- + The available models. Filtered by the `type` and `status` query parameters + when supplied. + type: array + items: + $ref: "../generationmodel.yaml#/GenerationModel" + required: + - models + type: object From de2a8ba6835a4cfe116bde0ae62334954fb08c71 Mon Sep 17 00:00:00 2001 From: dazzatronus Date: Fri, 21 Aug 2026 10:32:31 +1000 Subject: [PATCH 2/3] docs: drop the status filter that cannot vary --- paths/models.yaml | 13 +------------ schemas/generationmodel.yaml | 12 ------------ 2 files changed, 1 insertion(+), 24 deletions(-) diff --git a/paths/models.yaml b/paths/models.yaml index af635a9..e494595 100644 --- a/paths/models.yaml +++ b/paths/models.yaml @@ -20,7 +20,7 @@ schema: $ref: "../schemas/responses/generationmodellistresponse.yaml#/GenerationModelListResponse" "400": - description: An unknown `type` or `status` was supplied. + description: An unknown `type` was supplied. security: - DeveloperKey: [] tags: @@ -37,17 +37,6 @@ - video - audio example: video - - in: query - name: status - required: false - description: Return only models with this lifecycle status. - schema: - type: string - enum: - - active - - experimental - - deprecated - example: active - in: query name: expand required: false diff --git a/schemas/generationmodel.yaml b/schemas/generationmodel.yaml index da17d61..9d0bf79 100644 --- a/schemas/generationmodel.yaml +++ b/schemas/generationmodel.yaml @@ -19,17 +19,6 @@ - video - audio example: video - status: - description: >- - `active` for a model in general use, `experimental` for one that may change, - and `deprecated` for one scheduled for removal. Warn before a deprecated - model disappears. - type: string - enum: - - active - - experimental - - deprecated - example: active pricing: description: What one generation with this model costs. $ref: "./generationmodelpricing.yaml#/GenerationModelPricing" @@ -43,5 +32,4 @@ required: - model - type - - status type: object From f9899e76df07551f631dde5b8ca8bdbffc07adee Mon Sep 17 00:00:00 2001 From: dazzatronus Date: Fri, 21 Aug 2026 10:34:12 +1000 Subject: [PATCH 3/3] docs: drop the type filter clients can apply themselves --- paths/models.yaml | 16 ++-------------- .../responses/generationmodellistresponse.yaml | 4 +--- 2 files changed, 3 insertions(+), 17 deletions(-) diff --git a/paths/models.yaml b/paths/models.yaml index e494595..1782a86 100644 --- a/paths/models.yaml +++ b/paths/models.yaml @@ -5,7 +5,8 @@ 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. + 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`. @@ -19,24 +20,11 @@ application/json: schema: $ref: "../schemas/responses/generationmodellistresponse.yaml#/GenerationModelListResponse" - "400": - description: An unknown `type` was supplied. security: - DeveloperKey: [] tags: - Edit parameters: - - in: query - name: type - required: false - description: Return only models generating this asset type. - schema: - type: string - enum: - - image - - video - - audio - example: video - in: query name: expand required: false diff --git a/schemas/responses/generationmodellistresponse.yaml b/schemas/responses/generationmodellistresponse.yaml index eced5be..bc635ec 100644 --- a/schemas/responses/generationmodellistresponse.yaml +++ b/schemas/responses/generationmodellistresponse.yaml @@ -2,9 +2,7 @@ description: The generation models available to this account. properties: models: - description: >- - The available models. Filtered by the `type` and `status` query parameters - when supplied. + description: The available models. type: array items: $ref: "../generationmodel.yaml#/GenerationModel"