How do I determine or specify a model version?

Does the model served by the same name change over time?

Yes, we periodically update our models to improve performance and resolve issues. Typically, this may happen every few months. For instance, if you specify model=nova-2, we may update the model serving Nova-2 requests when we have new changes to release.

How do I determine which model version I'm using?

In a JSON request response, inspect the property response["metadata"]["model_info"]. That field will include a model UUID, under which it lists a name, version, and "arch" (architecture).

Both the model UUID and model version can be used to identify a specific, fixed model.

{
    "metadata": {
            "model_info": {
                    "30089e05-99d1-4376-b32e-c263170674af": {
                            "name": "2-general-nova",
                            "version": "2024-01-09.29447",
                            "arch": "nova-2"
                    }
            }
            ...
    },
    ...
}

How do I "pin" or always use the same version?

You may specify a version parameter in your request, by adding the parameter version=<version>. For instance, in the above example, you'd specify version=2024-01-09.29447.

Note that model UUID may be used to identify a model, but it is not supported to specify a model in a request parameter.

What are the risks or downsides to pinning a model version?

You will not automatically use our latest models.

You will need to manually choose to upgrade your version number if you ever want to use a newer model.

We do not guarantee support or access to specific older versions.

We highly recommend falling back to version=latest in case a specified model version becomes unsupported. Otherwise, your requests may fail if we remove access to an older model version that you depend on.

Can I fetch all historical versions of a given model?

You may use the GET /models API in order to get the metadata of all latest versions of our models.

To also fetch historical versions, add the parameter include_outdated=true.

See our Get Models API reference for further details.