Biz Client API reference

Module modules/biz-client, POSIX target tuya_biz_client, public headers tuya_biz_client.h and tuya_ai_role.h. See AI role management for integration.

Client and lifetime​

int tuya_biz_client_create(iot_client_t *iot, const char *request_lang,
                           tuya_biz_client_t **out);
void tuya_biz_client_destroy(tuya_biz_client_t *client);

Borrows the IoT Client and its PAL. NULL request_lang defaults to zh; nonempty values can occupy at most 31 bytes. Failure clears *out. Initialize IoT first; free results before destroying Biz Client and finish all calls before IoT teardown. Instances keep separate contexts and label languages; the application owns serialized scheduling.

Role APIs​

All operations take a Biz Client first and optional iot_atop_rejection_t * last. Complete signatures are in the public header.

Every request includes t; list queries also include display requestLang. Timbre queries use lang; NULL means unfiltered. No hidden next-page request.

Types​

tuya_ai_role_t has role_id, template_id, type, name, description, image_url, lang_code, lang_name, timbre_id, timbre_name, speed. List queries stamp the source role type. Bound-role queries read the cloud type and default an omitted type to SINGLE.

tuya_ai_role_edit_t has optional name, lang_code, timbre_id pointers, plus set_speed and speed. Templates create and request binding; custom roles update in place. out_id needs TUYA_AI_ROLE_ID_LEN bytes and is cleared on failure. Skip calls when nothing changed.

Role and timbre lists have items, count, total_count (-1 if unknown). Language lists have items and count. Timbre support_langs is a comma-separated display field preserving full codes; cloud filtering uses the original language code.

List responses may be arrays or arrays under datas, list, records, rows, content, data, items. Unknown shapes are rejected. Required role IDs, language codes and voice IDs must be nonempty; oversized fields reject the whole result rather than returning a partial list.

Bind, delete and update acknowledgements retain compatibility with the existing TuyaOpen role implementation: after a successful ATOP envelope, a non-null, non-false JSON result is opaque acknowledgement, not necessarily a Boolean. Template creation specifically requires a nonempty new ID string. Read back the binding to verify the intended role was selected.

Release and errors​

void tuya_ai_role_list_free(tuya_biz_client_t *, tuya_ai_role_list_t *);
void tuya_ai_language_list_free(tuya_biz_client_t *, tuya_ai_language_list_t *);
void tuya_ai_timbre_list_free(tuya_biz_client_t *, tuya_ai_timbre_list_t *);

Release through the original live context. Lists are zeroed after release; failed queries leave empty outputs. Destroying the context does not free outstanding result lists.

Deletion does not query role provenance first; callers submit only confirmed custom IDs. No avatar download, NVS, RTC calls or automatic retry occur.