refactor(api): adopt opaque options, tensors, and results

CMakeLists.txt

@@ -240,6 +240,8 @@ file(GLOB SD_LIB_SOURCES CONFIGURE_DEPENDS
     "src/*.h"
     "src/*.cpp"
     "src/*.hpp"
+    "src/api/*.h"
+    "src/api/*.cpp"
     "src/conditioning/*.h"
     "src/conditioning/*.cpp"
     "src/conditioning/*.hpp"
@@ -431,6 +433,9 @@ target_include_directories(${SD_LIB} PUBLIC include)
 target_include_directories(${SD_LIB} PRIVATE src src/core)
 target_include_directories(${SD_LIB} PUBLIC thirdparty)
 target_compile_features(${SD_LIB} PUBLIC c_std_11 cxx_std_17)
+set_target_properties(${SD_LIB} PROPERTIES
+    CXX_VISIBILITY_PRESET hidden
+    VISIBILITY_INLINES_HIDDEN ON)
 
 
 if (SD_BUILD_EXAMPLES)

docs/README.md

@@ -15,6 +15,7 @@ For the project overview and supported models, see the [project README](../READM
 
 ## Generation and inputs
 
+- [C API and migration](guides/c_api.md)
 - [Sampling methods and schedulers](guides/sampling.md)
 - [Image editing](guides/edit.md)
 - [Images in prompts](guides/prompt_images.md)
@@ -38,6 +39,7 @@ For the project overview and supported models, see the [project README](../READM
 
 ## Development
 
+- [C API internals](development/c_api.md)
 - [Model configuration and integration conventions](development/model_config.md)
 - [ggml operator extensions](development/ggml_extensions.md)
 - [Backend performance probes](development/backend_probe.md)

docs/development/c_api.md

@@ -0,0 +1,63 @@
+# C API Internals
+
+The public declarations live in [stable-diffusion.h](../../include/stable-diffusion.h).
+See the [C API guide](../guides/c_api.md) for keys, value types and ownership rules.
+
+## Internal modules
+
+| Module | Responsibility |
+| --- | --- |
+| `src/api/options.h/.cpp` | Opaque options, key registration, setter validation and conversion to typed configuration. |
+| `src/config.h/.cpp` | Typed configuration and the library defaults for each configuration group. |
+| `src/api/tensor.h/.cpp` | Opaque tensor handles backed by `sd::Tensor<T>`, reference counting and conversion to private media views. |
+| `src/core/media.h` | Private raw media views used by inference and codecs. |
+| `src/api/result.h/.cpp` | Internal result storage, opaque result accessors, metadata attachment and media ownership. |
+| `src/api/api.h/.cpp` | Context, generation, callback and query entry points, plus thread-local diagnostics and exception-to-status handling. |
+| `src/generation_info.h/.cpp` | Construction of generation metadata JSON. |
+| `src/pipeline/generation.h` | Internal generation entry declarations. |
+| `src/stable-diffusion.cpp` | Internal typed image/video generation and model-specific validation. |
+| `src/core/option_types.h/.cpp` | Internal mode enums, name lookup and parsing. |
+
+Options are validated and converted once at the API boundary. The runtime reads
+typed configuration fields. Internal callers such as ADetailer pass typed
+configuration directly to the internal generation entry; they do not rebuild
+options or call public setters.
+
+The option map alone records whether a key was supplied. Zero, false, empty
+strings and explicit automatic choices remain entries until `unset` removes
+them. Each conversion starts with a fresh `OptConfig`, then overlays supplied
+values and validates combinations. Reusing the output configuration cannot
+retain a previous request's overrides. ADetailer applies its operation-specific
+strength default before the overlay.
+
+Fixed defaults live in the configuration constructors. Internal automatic
+policies (such as model-selected sampler/scheduler and automatic eta/flow shift)
+are resolved by the pipeline after refreshing the model sources. Their internal
+sentinel values describe an automatic policy, not the presence of an input key.
+Do not infer presence by comparing a typed value against its default.
+
+CLI/server inference inputs use `std::optional`; their option builders emit
+only engaged fields. Recipe defaults fill missing startup inputs; request
+fields then override the configured recipe/startup values. Explicit empty
+numeric arrays replace inherited arrays, and JSON `null` clears an optional
+input. Frontend-only settings such as output formats and listen ports keep
+local defaults. Frontend checks cover request syntax, file inputs and server
+resource policy. Parameter ranges are checked by the public setters used by the
+option builders; combinations and model applicability are checked when executing.
+Examples include only public library headers and do not query library defaults.
+Capability defaults describe configured overrides; null means that the library
+selects the value, and result metadata reports effective values. Post-generation
+ADetailer clears inherited dimensions and strength before applying pass overrides,
+so its operation defaults also come from the library.
+
+Result storage owns tensors and metadata. Tensor handles contain a dtype-specific
+`sd::Tensor<T>` and an atomic reference count; options retain handles rather than
+copying tensor payloads. Raw pipeline output buffers are converted to tensors at
+the boundary and released there. Internal producers with an `sd::Tensor<T>` can
+move it directly into a handle. Video results keep per-frame tensors and assemble
+a contiguous video tensor only when requested. Cached assembly is synchronized.
+Preview tensors are independent snapshots and may be retained by callbacks.
+Metadata construction is separate from its attachment to a result.
+
+These headers are private implementation details and are not installed as part
+of the public C API.

docs/guides/backend.md

@@ -273,8 +273,8 @@ flags are deprecated and emit a warning, but remain supported when
 `--conv-direct` is omitted. Use `--conv-direct auto,diffusion=on,controlnet=on`
 and `--conv-direct auto,vae=on`, respectively. An explicit
 `--conv-direct` takes precedence over both legacy flags regardless of order.
-Library callers can set the appended `sd_ctx_params_t::conv_direct_mode` field
-to the same string; null or empty selects `auto` while honoring legacy true
+Library callers can set the `conv_direct_mode` context-option key with
+`sd_opt_set_string()` to the same string; unset or empty selects `auto` while honoring legacy true
 flags. The context copies the string.
 
 ## Flash attention (`--flash-attn on|off|auto`)
@@ -339,9 +339,10 @@ row-split configurations, which can fall back to layer split during initializati
 Use `--flash-attn on` and `--flash-attn off,diffusion=on`, respectively.
 Both aliases write the same mode string as `--flash-attn`; the last occurrence
 of any of these options wins. Library callers
-can set `sd_ctx_params_t::flash_attn_mode` to the same string, including
+can set the `flash_attn_mode` context-option key with `sd_opt_set_string()`
+to the same string, including
 `"on"`, `"off"`, `"auto"`, or `"auto,te=off,vae=on"`.
-A null or empty string uses automatic selection unless a
+An unset or empty string uses automatic selection unless a
 legacy `flash_attn` or `diffusion_flash_attn` boolean is set. The context copies
 the string; no new enum is required.