Fast Ref API — Overview — Fast Ref API Reference

Fast Ref API is a Python interface for automating Fast Ref workflows from external scripts. Designed for Technical Artists (TAs) at partner studios.

v2 Key Changes

Item	v1	v2
Import	5-line sys.path boilerplate required	One line: `from os_fast_ref.api import FastRefAPI`
Public methods	16	20
Write operations	Confirmation dialog may appear in some scene states	Always silent (no dialogs)
FBX export	`fbx_options=dict` only	`preset=` keyword added
slot type validation	Range/empty-slot only	int type check added (including bool)
Max supported versions	2022 / 2025	2022 / 2025 / 2027

Design Principles

Item	Policy
READ operations	No UI required — reads directly from scene InfoNode
WRITE operations	UI-independent + always silent
Data loading	Session-level caching
FBX options	`preset` keyword or `dict`
Public surface	Fixed at 20 methods (semver guarantee)

API Method List (20 methods)

Category	Method	Description
Query	`get_reference_list()`	Returns the list of references in the scene
Query	`check_file_status()`	Checks source file status (latest/outdated/missing)
Query	`get_outdated_references()`	Returns only OUTDATED references [v2 new]
Query	`get_fbx_default_options()`	Returns current FBX default preset options
Query	`refresh()`	Force-rescans the InfoNode [v2 new]
Manage	`add_reference()`	Add a reference
Manage	`remove_reference()`	Remove a reference
Manage	`replace_reference()`	Replace a reference file
Manage	`reload_reference()`	Reload a single reference
Manage	`reload_all_references()`	Reload all references
Manage	`reload_outdated_references()`	Reload only OUTDATED references [v2 new]
FBX Export	`export_fbx()`	Export a single reference as FBX (preset support)
FBX Export	`export_fbx_all()`	Export all references as FBX in batch (preset support)
Advanced	`merge_reference()`	Convert a single reference to scene objects
Advanced	`merge_all_references()`	Convert all references to scene objects
Advanced	`set_space_activate()`	Toggle namespace ON/OFF
Advanced	`set_unpack()`	Toggle Unpack ON/OFF
Advanced	`convert_to_reference()`	Convert selected objects to a reference
UI	`update_ui()`	Manually refresh Fast Ref UI

Key Concepts

Slot

Fast Ref manages references in slots 0–9. In v2, slot must be an int.

api.remove_reference(slot=0)     # OK
api.remove_reference(slot="0")   # TypeError: slot must be int
api.remove_reference(slot=True)  # TypeError: slot must be int

Space Activate

Controls whether namespace prefixes are applied to a reference. When OFF, namespace prefixes are removed from node, layer, and SelectionSet names.

Unpack

Detaches reference nodes from their top-level group container and moves them to the world level.

FBX Preset (v2 new)

Specifying the preset= keyword in export_fbx / export_fbx_all applies a saved preset with a single word.

api.export_fbx(slot=0, output_path=r"J:\output\char.fbx", preset="Unreal_Ani")

Non-existent preset name → immediately raises ValueError.

Return Value Structure

{"success": bool, "message": str}
# on failure, also includes:
{"success": False, "message": str, "error": str}

Error Handling Rules

Situation	Behavior
File does not exist	Raises `FileNotFoundError`
Invalid slot number / empty slot	Raises `ValueError`
slot is not int (including bool)	Raises `TypeError` [v2 new]
Non-existent FBX preset name	Raises `ValueError` [v2 new]
Invalid argument type	Raises `TypeError`
License authentication failure	Raises `PermissionError` during initialization
Operation failure (recoverable)	Returns `{"success": False, ...}`