docs: add TTS migration guide for 1.1.0-RC1

- Add comprehensive migration guide with find/replace patterns
- Include side-by-side code examples (old vs new API)
- Add provider-agnostic usage examples and best practices
- Document breaking changes in 1.1.0-RC1 upgrade notes

Author: markpollack

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/audio/speech.adoc

@@ -87,7 +87,11 @@ byte[] audioBytes = response.getResult().getOutput();
 TextToSpeechResponseMetadata metadata = response.getMetadata();
 ----
 
-== Writing Portable Code
+== Writing Provider-Agnostic Code
+
+One of the key benefits of the shared TTS interfaces is the ability to write code that works with any TTS provider without modification. The actual provider (OpenAI, ElevenLabs, etc.) is determined by your Spring Boot configuration, allowing you to switch providers without changing application code.
+
+=== Basic Service Example
 
 The shared interfaces allow you to write code that works with any TTS provider:
 
@@ -103,6 +107,7 @@ public class NarrationService {
     }
 
     public byte[] narrate(String text) {
+        // Works with any TTS provider
         return textToSpeechModel.call(text);
     }
 
@@ -116,6 +121,214 @@ public class NarrationService {
 
 This service works seamlessly with OpenAI, ElevenLabs, or any other TTS provider, with the actual implementation determined by your Spring Boot configuration.
 
+=== Advanced Example: Multi-Provider Support
+
+You can build applications that support multiple TTS providers simultaneously:
+
+[source,java]
+----
+@Service
+public class MultiProviderNarrationService {
+
+    private final Map<String, TextToSpeechModel> providers;
+
+    public MultiProviderNarrationService(List<TextToSpeechModel> models) {
+        // Spring will inject all available TextToSpeechModel beans
+        this.providers = models.stream()
+            .collect(Collectors.toMap(
+                model -> model.getClass().getSimpleName(),
+                model -> model
+            ));
+    }
+
+    public byte[] narrateWithProvider(String text, String providerName) {
+        TextToSpeechModel model = providers.get(providerName);
+        if (model == null) {
+            throw new IllegalArgumentException("Unknown provider: " + providerName);
+        }
+        return model.call(text);
+    }
+
+    public Set<String> getAvailableProviders() {
+        return providers.keySet();
+    }
+}
+----
+
+=== Streaming Audio Example
+
+The shared interfaces also support streaming for real-time audio generation:
+
+[source,java]
+----
+@Service
+public class StreamingNarrationService {
+
+    private final TextToSpeechModel textToSpeechModel;
+
+    public StreamingNarrationService(TextToSpeechModel textToSpeechModel) {
+        this.textToSpeechModel = textToSpeechModel;
+    }
+
+    public Flux<byte[]> streamNarration(String text) {
+        // TextToSpeechModel extends StreamingTextToSpeechModel
+        return textToSpeechModel.stream(text);
+    }
+
+    public Flux<TextToSpeechResponse> streamWithMetadata(String text, TextToSpeechOptions options) {
+        TextToSpeechPrompt prompt = new TextToSpeechPrompt(text, options);
+        return textToSpeechModel.stream(prompt);
+    }
+}
+----
+
+=== REST Controller Example
+
+Building a REST API with provider-agnostic TTS:
+
+[source,java]
+----
+@RestController
+@RequestMapping("/api/tts")
+public class TextToSpeechController {
+
+    private final TextToSpeechModel textToSpeechModel;
+
+    public TextToSpeechController(TextToSpeechModel textToSpeechModel) {
+        this.textToSpeechModel = textToSpeechModel;
+    }
+
+    @PostMapping(value = "/synthesize", produces = "audio/mpeg")
+    public ResponseEntity<byte[]> synthesize(@RequestBody SynthesisRequest request) {
+        byte[] audio = textToSpeechModel.call(request.text());
+        return ResponseEntity.ok()
+            .contentType(MediaType.parseMediaType("audio/mpeg"))
+            .header("Content-Disposition", "attachment; filename=\"speech.mp3\"")
+            .body(audio);
+    }
+
+    @GetMapping(value = "/stream", produces = MediaType.APPLICATION_OCTET_STREAM_VALUE)
+    public Flux<byte[]> streamSynthesis(@RequestParam String text) {
+        return textToSpeechModel.stream(text);
+    }
+
+    record SynthesisRequest(String text) {}
+}
+----
+
+=== Configuration-Based Provider Selection
+
+Switch between providers using Spring profiles or properties:
+
+[source,yaml]
+----
+# application-openai.yml
+spring:
+  ai:
+    model:
+      audio:
+        speech: openai
+    openai:
+      api-key: ${OPENAI_API_KEY}
+      audio:
+        speech:
+          options:
+            model: gpt-4o-mini-tts
+            voice: alloy
+
+# application-elevenlabs.yml
+spring:
+  ai:
+    model:
+      audio:
+        speech: elevenlabs
+    elevenlabs:
+      api-key: ${ELEVENLABS_API_KEY}
+      tts:
+        options:
+          model-id: eleven_turbo_v2_5
+          voice-id: your_voice_id
+----
+
+Then activate the desired provider:
+[source,bash]
+----
+# Use OpenAI
+java -jar app.jar --spring.profiles.active=openai
+
+# Use ElevenLabs
+java -jar app.jar --spring.profiles.active=elevenlabs
+----
+
+=== Using Portable Options
+
+For maximum portability, use only the common `TextToSpeechOptions` interface methods:
+
+[source,java]
+----
+@Service
+public class PortableNarrationService {
+
+    private final TextToSpeechModel textToSpeechModel;
+
+    public PortableNarrationService(TextToSpeechModel textToSpeechModel) {
+        this.textToSpeechModel = textToSpeechModel;
+    }
+
+    public byte[] createPortableNarration(String text) {
+        // Use provider's default options for maximum portability
+        TextToSpeechOptions defaultOptions = textToSpeechModel.getDefaultOptions();
+        TextToSpeechPrompt prompt = new TextToSpeechPrompt(text, defaultOptions);
+        TextToSpeechResponse response = textToSpeechModel.call(prompt);
+        return response.getResult().getOutput();
+    }
+}
+----
+
+=== Working with Provider-Specific Features
+
+When you need provider-specific features, you can still use them while maintaining a portable codebase:
+
+[source,java]
+----
+@Service
+public class FlexibleNarrationService {
+
+    private final TextToSpeechModel textToSpeechModel;
+
+    public FlexibleNarrationService(TextToSpeechModel textToSpeechModel) {
+        this.textToSpeechModel = textToSpeechModel;
+    }
+
+    public byte[] narrate(String text, TextToSpeechOptions baseOptions) {
+        TextToSpeechOptions options = baseOptions;
+
+        // Apply provider-specific optimizations if available
+        if (textToSpeechModel instanceof OpenAiAudioSpeechModel) {
+            options = OpenAiAudioSpeechOptions.builder()
+                .from(baseOptions)
+                .model("gpt-4o-tts")  // OpenAI-specific: use high-quality model
+                .speed(1.0)
+                .build();
+        } else if (textToSpeechModel instanceof ElevenLabsTextToSpeechModel) {
+            // ElevenLabs-specific options could go here
+        }
+
+        TextToSpeechPrompt prompt = new TextToSpeechPrompt(text, options);
+        TextToSpeechResponse response = textToSpeechModel.call(prompt);
+        return response.getResult().getOutput();
+    }
+}
+----
+
+=== Best Practices for Portable Code
+
+1. **Depend on Interfaces**: Always inject `TextToSpeechModel` rather than concrete implementations
+2. **Use Common Options**: Stick to `TextToSpeechOptions` interface methods for maximum portability
+3. **Handle Metadata Gracefully**: Different providers return different metadata; handle it generically
+4. **Test with Multiple Providers**: Ensure your code works with at least two TTS providers
+5. **Document Provider Assumptions**: If you rely on specific provider behavior, document it clearly
+
 == Provider-Specific Features
 
 While the shared interfaces provide portability, each provider also offers specific features through provider-specific options classes (e.g., `OpenAiAudioSpeechOptions`, `ElevenLabsSpeechOptions`). These classes implement the `TextToSpeechOptions` interface while adding provider-specific capabilities.