Skip to content

Tokenhub API Reference โ€‹

Updated

Base URL: https://tokenhub-intl.tencentcloudmaas.comAuthentication: Tokenhub API Key / Bearer

This page covers the authentication, request methods, and result handling specifications required for image and video generation. Model-specific parameters and examples are available in the model documents below.

Call Specification โ€‹

API Keys and Authentication โ€‹

Issue a key under API Key Management in the Tokenhub console. Pass the same key in the Authorization header of every generation and query request.

http
Authorization: Bearer $TOKENHUB_API_KEY
Content-Type: application/json

Manage API keys as server-side environment variables. In the JSON body, pass only the fields defined in the model-specific documents.

Endpoints and Regions โ€‹

All examples use the international gateway tokenhub-intl.tencentcloudmaas.com. Because the URL path varies by generation method, use the path given in the model-specific document. Do not pass a separate Region parameter.

The example reference files are stored in Singapore COS (ap-singapore). Download result files from the URL returned in the API response.

API List and Request Parameters โ€‹

For the generation and query API and input fields of each model, see the documents in the engine catalog below. The task ID and result fields may differ from engine to engine.

Responses and Execution Flow โ€‹

Synchronous Requests โ€‹

Hy Image and Seedream Image return the result in the response to the generation request. The response fields and the image delivery format follow the response specification of each model.

Asynchronous Tasks โ€‹

  1. Send the generation request and store the returned task ID.
  2. Check the status through the query path of that model.
  3. Once the status is complete, read the result URL and download the file.

The task ID field and the completion status differ by model. When handling query responses, distinguish between the values below.

ModelTask ID in the generation responseSuccess status in the query response
WAND-Vega-Imagetask_idstatus=completed
WAND-Vega-Videoidstatus=succeeded
Vidu Imagetask_idstate=success
PixVerse VideoResp.video_idResp.status=1
Kling Videodata.iddata.status=succeeded
MiniMax Videotask_idtask.status=succeeded
Hy Videotask_idstatus=succeeded

The polling interval and failure statuses follow the query specification of each model. Once a generation request has been accepted, do not resubmit the same request โ€” query the result by task ID instead.

Errors and Call Limits โ€‹

Error Handling โ€‹

HTTP statusWhat to check
400Model ID, required fields, parameter format, and input limits
401Whether the API key is valid, and the Authorization: Bearer header
429Call frequency and usage quota
5xxService error. If you already received an asynchronous task ID, query the task status first

Use the request identifier and error code in the error response to diagnose the problem. For the error structure of each model, see the error code section of the corresponding document.

Request Examples โ€‹

Use the request example for the model or protocol you are calling. Do not mix authentication methods and request fields from different paths in one request. Review the engine documents below together with the parameters for each protocol.

Results and Resource Management โ€‹

Reference Files and Result Storage โ€‹

Reference URLs must be reachable by the API server. File format, size, and count limits, as well as video duration limits, follow the input conditions of each model. Download and store signed result URLs within their validity period.

Example fileURL
Reference imagehttps://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/reference-cup.png
Reference videohttps://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/vega-pro-example.mp4

Image โ€‹

ModelModel IDCall method
Hyhy-image-v3.5-preview / hy-image-v3Synchronous
WAND-Vega-Imagewand-vega-image-pro / wand-vega-image-flash / wand-vega-image-liteAsynchronous
Viduvidu-image-q2Asynchronous
Seedreamseedream-image-v5.0-pro / seedream-image-v5.0-liteSynchronous

Video โ€‹

ModelModel IDCall method
WAND-Vega-Videowand-vega-video-1.5-pro / wand-vega-video-1.0-pro / wand-vega-video-1.0-liteAsynchronous
PixVersepixverse-video-v6.0 / pixverse-video-c1Asynchronous
Klingkling-video-v3 / kling-video-v3-omni / kling-video-v3-turboAsynchronous
MiniMaxminimax-video-h3 / minimax-video-h3-maxAsynchronous
Hyhy-video-v1.5Asynchronous

Pricing and Official Guides โ€‹

Tokenhub model pricing / API error codes

CategoryOfficial guide
ImageOverview / Vega / Hy / Vidu / Seedream
VideoOverview / PixVerse / Kling / MiniMax / Hy

Built with VitePress ยท Deployed on Tencent EdgeOne Pages