Fish Audio inference APIs accept the standard W3C Trace Context traceparent
header. Send this header when your application already has an active trace and
you want Fish Audio edge, inference, alignment, and upstream ASR spans to appear
under the same trace ID.
Supported inference surfaces:
POST /v1/ttsPOST /v1/tts/stream/with-timestampPOST /v1/asrwss://api.fish.audio/v1/tts/live
If traceparent is omitted or invalid, Fish Audio starts a new trace for the
request. Tracing does not change authentication, rate limits, billing, request
priority, or generated output.
Use the W3C traceparent format:
traceparent: 00-<trace-id>-<parent-id>-<trace-flags>
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
4bf92f3577b34da6a3ce929d0e0e4736 is the trace ID. Fish Audio
continues that trace ID when it calls the inference backend and related services.
Prefer letting your tracing SDK inject traceparent instead of hand-building
it. For each Fish Audio request, create a child span in your business service
and inject that span context into the outgoing HTTP or WebSocket headers.
Bind Business and Inference Traces
To bind your business-side trace to Fish Audio’s inference-side trace:
- Start or continue a trace in your application for the user workflow.
- Create a child span around the Fish Audio request.
- Inject that span context into the request headers.
- Send the request with
traceparent.
- Use the same trace ID in your observability tool to inspect both your
business spans and Fish Audio inference spans.
For multiple Fish Audio calls in one workflow, keep the same trace ID by using
the same parent trace, but let your tracing SDK create a fresh parent/span ID for
each outgoing request.
REST Example
TRACEPARENT="00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
curl --request POST https://api.fish.audio/v1/tts \
--header "Authorization: Bearer $FISH_API_KEY" \
--header "Content-Type: application/json" \
--header "model: s2-pro" \
--header "traceparent: $TRACEPARENT" \
--data '{
"text": "Hello from a traced Fish Audio request.",
"reference_id": "model-id",
"format": "mp3"
}' \
--output out.mp3
OpenTelemetry Examples
import os
import requests
from opentelemetry import trace
from opentelemetry.propagate import inject
tracer = trace.get_tracer("my-service")
with tracer.start_as_current_span("fish_audio.tts"):
headers = {
"Authorization": f"Bearer {os.environ['FISH_API_KEY']}",
"Content-Type": "application/json",
"model": "s2-pro",
}
inject(headers)
response = requests.post(
"https://api.fish.audio/v1/tts",
headers=headers,
json={
"text": "Hello from a traced request.",
"reference_id": "model-id",
"format": "mp3",
},
timeout=60,
)
response.raise_for_status()
import { context, propagation, trace } from "@opentelemetry/api";
const tracer = trace.getTracer("my-service");
const span = tracer.startSpan("fish_audio.tts");
const ctx = trace.setSpan(context.active(), span);
try {
await context.with(ctx, async () => {
const headers = {
Authorization: `Bearer ${process.env.FISH_API_KEY}`,
"Content-Type": "application/json",
model: "s2-pro",
};
propagation.inject(ctx, headers);
const response = await fetch("https://api.fish.audio/v1/tts", {
method: "POST",
headers,
body: JSON.stringify({
text: "Hello from a traced request.",
reference_id: "model-id",
format: "mp3",
}),
});
if (!response.ok) {
throw new Error(`${response.status} ${await response.text()}`);
}
});
} finally {
span.end();
}
WebSocket Tracing
Pass traceparent on the WebSocket upgrade request:
import WebSocket from "ws";
const ws = new WebSocket("wss://api.fish.audio/v1/tts/live", {
headers: {
Authorization: `Bearer ${process.env.FISH_API_KEY}`,
model: "s2-pro",
traceparent: "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
},
});
Browser WebSocket APIs do not allow custom headers. For browser clients,
inject traceparent from a trusted server-side proxy or use REST endpoints
where your frontend can send the header through fetch.
Fish Audio supports trace-based performance analysis for enterprise customers
with a signed enterprise agreement. When this support is enabled, share the
W3C trace ID with Fish Audio support so we can correlate your business span
with Fish Audio edge routing, backend inference, reference-audio encoding,
TTFT, response-time, alignment, and upstream ASR spans.
traceparent value needed for investigation. Do not
place API keys, user identifiers, transcripts, audio URLs, or other sensitive
data in trace IDs or span names. 
