Common Types and Errors

Speech, translation, interpretation, recording, and image generation share language, audio format, task, callback, and error contracts.

TSAIAudioFormat

Value	Raw value	Description
TSAIAudioFormatUnknown	-1	Unknown format
TSAIAudioFormatNone	0	No audio in results; inspect file header in configurations
TSAIAudioFormatPcm	1	PCM
TSAIAudioFormatOpus	2	Opus
TSAIAudioFormatMp3	3	MP3
TSAIAudioFormatWav	4	WAV

Raw PCM has no header and requires explicit format, sample-rate, channel, and bit-depth information.

TSAILanguage

TSAILanguage is shared across AI services and is distinct from the device-UI TSLanguageType.

Name	Value	Name	Value
Unknown	-1	Auto	0
ChineseSimplified	1	ChineseTraditional	2
EnglishUS	3	EnglishUK	4
Japanese	5	Korean	6
French	7	German	8
Spanish	9	Russian	10
Portuguese	11	Indonesian	12
Malay	13	Filipino	14
Thai	15	Arabic	16
Vietnamese	17	Danish	18
Greek	19	Finnish	20
Hindi	21	Italian	22
Dutch	23	Norwegian	24
Polish	25	Swedish	26
Swahili	27	Turkish	28
Bengali	29	Romanian	30
Nepali	31	Ukrainian	32
Czech	33	Welsh	34
Hungarian	35	Icelandic	36
Georgian	37	Kazakh	38
Luxembourgish	39	Latvian	40
Malayalam	41	Slovak	42
Slovenian	43	Serbian	44
Telugu	45	Catalan	46
Tamil	47	Urdu	48
Croatian	49	Bulgarian	50
Lithuanian	51	Latin	52
Maori	53	Persian	54
Azerbaijani	55	Kannada	56
Estonian	57	Macedonian	58
Breton	59	Basque	60
Armenian	61	Mongolian	62
Bosnian	63	Albanian	64
Galician	65	Marathi	66
Punjabi	67	Sinhala	68
Khmer	69	Shona	70
Yoruba	71	Somali	72
Afrikaans	73	Occitan	74
Belarusian	75	Tajik	76
Sindhi	77	Gujarati	78
Amharic	79	Yiddish	80
Lao	81	Uzbek	82
Faroese	83	HaitianCreole	84
Pashto	85	Turkmen	86
NorwegianNynorsk	87	Maltese	88
Sanskrit	89	Burmese	90
Tibetan	91	Malagasy	92
Assamese	93	Tatar	94
Hawaiian	95	Lingala	96
Hausa	97	Bashkir	98
Javanese	99	Sundanese	100

Prefix each short name with TSAILanguage, for example TSAILanguageChineseSimplified.

Auto and Unknown

• Auto is valid only for translation or interpretation source-language detection.
• ASR, recording, and image generation reject Auto.
• Translation and interpretation targets must be concrete.
• Unknown usually means unset or current app localization; check each property contract.

BCP-47 mapping

+ (nullable NSString *)bcp47CodeForLanguage:(TSAILanguage)language;
+ (nullable NSString *)targetBcp47CodeForLanguage:(TSAILanguage)language;
+ (TSAILanguage)languageForBcp47Code:(nullable NSString *)code;

TSAIASRScene

Value	Raw value	Meaning
TSAIASRSceneUnknown	-1	Unspecified scene
TSAIASRSceneOnSite	1	Meetings, interviews, and other on-site recordings
TSAIASRSceneCall	2	Telephone or VoIP recordings

TSAIChatIntentType

Value	Raw value	Meaning
Unknown	-1	Unknown protocol intent; see intentId for the raw value
None	0	Conversation with no actionable intent
PhotoCapture / PhotoUnderstand	1 / 2	Capture / understand a photo
VideoStart / VideoStop	3 / 4	Start / stop video recording
AudioRecord	5	Start audio recording
VolumeUp / VolumeDown / VolumeSet	10 / 11 / 12	Volume controls
MusicPlay / MusicStop	20 / 21	Play / stop music
MusicNext / MusicPrev	22 / 23	Next / previous track
CallAnswer / CallDecline / CallRecord	30 / 31 / 32	Call controls
DeviceBatteryQuery / DevicePowerOff	40 / 41	Query battery / power off device
DialogExit / AgentSwitch / VoiceClone	50 / 51 / 52	Exit dialog / switch agent / clone voice

Prefix shortened values with TSAIChatIntentType, for example TSAIChatIntentTypePhotoCapture.

Task and callback conventions

1. Single tasks usually return a client-generated task ID synchronously.
2. Partial callbacks may run zero or more times; completion runs once on success, failure, or cancellation.
3. Completion is the authoritative terminal signal.
4. Logical cancellation may not stop server-side work, but late results are suppressed.
5. Callback queues are API-specific; question answering, image generation, and selected Context callbacks are explicitly main-thread.

TSAIErrorDomain

Error	Code	Description
TSAIErrorCodeInvalidParameter	1001	Invalid parameter
TSAIErrorCodeNotSupported	1002	Feature not supported
TSAIErrorCodeContextInactive	1003	Context inactive or stale
TSAIErrorCodeProviderUnavailable	1004	Provider unavailable
TSAIErrorCodeBridgeUnavailable	1005	Platform DeviceBridge unavailable
TSAIErrorCodeActivationSuperseded	1006	Activation superseded by a newer request
TSAIErrorCodeBusy	1007	Conflicting task is active
TSAIErrorCodeCancelled	1008	Task cancelled
TSAIErrorCodeAuthorizationRequired	1009	Provider authorization required
TSAIErrorCodeTaskFailed	1010	AI task failed
TSAIErrorCodeContentRejected	1011	Content rejected
TSAIErrorCodeTimeout	1012	Request timed out
TSAIErrorCodeNetworkUnavailable	1013	Network unavailable
TSAIErrorCodeInvalidResponse	1014	Invalid provider response
TSAIErrorCodeAudioRouteUnavailable	1015	No complete audio route satisfies the request or fallback policy
TSAIErrorCodeAudioRouteMismatch	1016	Use case, device scene, or reserved route does not match the request

if ([error.domain isEqualToString:TSAIErrorDomain]) {
    switch (error.code) {
        case TSAIErrorCodeAuthorizationRequired:
            TSLog(@"AI authorization is required");
            break;
        case TSAIErrorCodeNetworkUnavailable:
            TSLog(@"Network unavailable");
            break;
        case TSAIErrorCodeContextInactive:
            TSLog(@"Obtain the new activeContext");
            break;
        default:
            TSLog(@"AI operation failed: %@", error.localizedDescription);
            break;
    }
}

Never log app keys, tokens, device-authentication data, or raw user audio.