Hust Media Public API v3
Back to NotesThis note shows how shared API routing, payload validation, and response handling keep utility requests consistent, supporting platform growth through cleaner service flows and stable integration behavior.
Written date: 07/25/2025 22:43:14Engineering Notes
Introduction
This note documents the current v3 API contract behind the platform utilities. It focuses on the shared gateway structure, service-based request routing, and the response handling rules used by the client so integration and operational behavior stay consistent over time.
Authentication
All current utilities route through the same v3 gateway and require an API Key in the JSON body. Requests use Content-Type: application/json, while routing is handled by service and payload structure rather than separate endpoints for each utility.
Endpoint
POST /api/v3
This endpoint is the shared submission layer for the current utilities. In the client flow, each request starts with action: "add", username: "", a normalized national_market value ("vi" or "en"), and a utility-specific service id.
Request Body
The current client logic uses one common request contract and then adjusts a few fields per utility. Core fields include action, key, username, national_market, service, link, comments, and quantity.
The exact payload branch is selected by service id together with fields such as link, comments, or images_data.
In practice, link, comments, and quantity are reused differently depending on the selected service:
- Text to Speech sends normalized text through
linkwith a fixedquantity. - Speech to Text sends audio as base64 data in
comments.voice_data, withquantityderived from rounded audio duration. - Image to Text sends uploaded image data through
images_data, with a fixedquantityof1. - Vietnamese to English sends trimmed source text through
comments, withquantitybased on trimmed character length.
Response Handling
The client reads response.text() first, then attempts JSON parsing, and falls back to the raw text as a message when parsing fails. A request is treated as successful only when response.ok is true and the returned payload does not include an error field.
Depending on the service, the client reads result data from message, order, voice, text_vip, or text. For text-returning utilities, text_vip is preferred when both text fields are available.
Was this content helpful to you?