SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsastraflow-api

astraflow-api

Coding & development

View repository

Updated 10-16 05:06

About this skill

AstraFlow Platform Management API Calling Guide

AstraFlow is UCloud's dedicated AI development platform for enterprises, and its model service sub-platform is called UModelVerse. This skill only coversmanagement APIs(managing API keys, bills and orders, model marketplace queries, inference log queries, etc.), that is, the batch of interfaces under https://astraflow.ucloud.cn/reference/modelverse/ in the documentation.

First, be clear: management API ≠ model invocation API

The AstraFlow platform actually has two completely different sets of interface systems; do not confuse them:

  1. Model invocation API(OpenAI/Gemini-compatible interfaces, for example POST https://api.modelverse.cn/v1/chat/completions): used to actually call large models for inference. The authentication method is very simple; only an API key is needed in the request header Authorization: Bearer {api_key} , and no signature calculation is involved. This API key can be created in the console https://console.ucloud.cn/modelverse/experience/api-keys .
  2. Management API(the object covered by this skill, for example CreateUMInferAPIKey、ListUMInferRequestLogs): used to manage resources under the account, such as creating/deleting the inference API keys mentioned above, checking orders and bills, checking model marketplace data, checking inference logs, etc. This set of interfaces uses thePublicKey/PrivateKey signature authenticationof the UCloud general API system, which is the same authentication mechanism as the APIs of traditional product lines such as UCloud cloud hosts and cloud disks, and is completely different from the Bearer Token authentication of the "model invocation API".

All subsequent content is aimed at the second type (management API).

The 4 parameters that must be obtained before calling

To call any AstraFlow management API, the following 4 parameters are required:

Parameter Description
Region Business region, for example cn-wlcb. Determines which region's service the request is routed to
ProjectId Project ID. Used to distinguish resource ownership when an account has multiple projects; if not specified, the default project of the main account is used by default, butsub-accounts must specify it
PublicKey The public key of the UCloud account, which is a parameter required for both signature calculation and the request itself
PrivateKey The private key of the UCloud account, which only participates in local signature calculation,will notappear in request parameters, and will not be sent to the server

PublicKey/PrivateKey Obtain it on the "API Key Management" page of the UCloud console (an account-level key, not the model invocation API key mentioned above).

How to ask the user for these 4 parameters

  • If the user has not provided them, directly ask the user for them, or tell the user that they can be provided through environment variables. It is recommended to use the following set of variable names (suggested naming when there is no established convention in the current project; the actual naming can be adjusted according to user/project habits):
export ASTRAFLOW_PUBLIC_KEY="<public-key>"
export ASTRAFLOW_PRIVATE_KEY="<private-key>"
export ASTRAFLOW_REGION="cn-wlcb"
export ASTRAFLOW_PROJECT_ID="<project-id>"
  • PrivateKey is highly sensitive information: it is only used to calculate signatures locally, and must never appear in content echoed to the user, logs, generated code repository files, or commit records; before executing scripts involving it, confirm that debugging switches such as set -x that print variable values are not enabled.
  • If the user is not sure which Regionto choose, see the "Determining Region" section below.
  • If the user is not sure which ProjectId, see the "Determining ProjectId" section below.

Basic request format

  • Request address:https://api.ucloud.cn(UCloud unified gateway; specifically determined by the Action parameter in the request, which determines which backend service it is actually routed to)
  • Supports GET or POST，POST when using Content-Type: application/json
  • Every request must include the following 3 "common parameters", which is a general requirement of all UCloud APIs:
Parameter Type Required Description
Action string Yes API command name, for example CreateUMInferAPIKey、ListUMInferAPIKey
PublicKey string Yes User public key
Signature string Yes Signature calculated from the public key, private key, and all parameters of this request; see the next section

In addition to the common parameters, you also need to add the Action own business parameters (such as Region、ProjectId, as well as parameters specific to each API).

  • The response is JSON; common response fields:
Field Type Description
RetCode int 0 indicates success, non-0 indicates failure
Action string The command name corresponding to the request
Message string RetCode When non-0, indicates the reason for failure

When a call fails, first check RetCode/Message; common issues:170 missing signature,171 signature error,160/161 missing or nonexistent Action、292 project does not exist,294 access IP denied. For signature-related errors, first check parameter ordering, whether a parameter was omitted, and whetherPrivateKey is correct.

Signature calculation method

Signature is calculated from PublicKey、PrivateKey and all parameters of this requestall parameters(excluding Signature itself), using the SHA1 algorithm, as follows:

  1. Collect all parameters that will be sent in this request (common parameters Action、PublicKey, as well as all business parameters, such as Region、ProjectId, and parameters specific to the API), butexcluding Signature itself.
  2. Sort these parameters by parameter name inascending order(ASCII order).
  3. In the sorted order, concatenate each parameter's "parameter name" and "parameter value" in sequence into a string, without any HTTP escaping (do not URL encode).
  4. At theendof the concatenated string, append PrivateKey。
  5. Perform a SHA1 hash on the entire string; the resulting hexadecimal string (lowercase) is the value of Signature .

Encoding details:

  • Boolean values are encoded as the literal true / false。
  • If the fractional part of a floating-point number is 0, keep only the integer part (for example, 42.0 should be written as 42）。
  • Floating-point numbers cannot be represented in scientific notation.
  • Array-type parameters (for example, ModelNames.N) participate in sorting and concatenation according to their actual expanded key names, for example ModelNames.0、ModelNames.1。

Security example (use only placeholders and environment variables; do not write any usable keys in the documentation):

  • PublicKey: read from ASTRAFLOW_PUBLIC_KEY .
  • PrivateKey: read only from ASTRAFLOW_PRIVATE_KEY , and do not write it into command literals, logs, or repository files.
  • Request parameters:Action=DescribeUHostInstance、Region=cn-bj2、Limit=10。

Use shell to compute the signature locally and save the result to an environment variable (before executing, confirm that it is not enabled set -x）：

ASTRAFLOW_SIGNATURE="$(
  printf '%s' "ActionDescribeUHostInstanceLimit10PublicKey${ASTRAFLOW_PUBLIC_KEY}Regioncn-bj2${ASTRAFLOW_PRIVATE_KEY}" |
    sha1sum |
    awk '{print $1}'
)"

After computing the Signature, add it as an ordinary parameter to the final request and send it together with the other parameters.

Request example

curl -X POST \
  https://api.ucloud.cn \
  -H 'Content-Type: application/json' \
  -d '{
      "Action"     : "DescribeUHostInstance",
      "Limit"      : 10,
      "PublicKey"  : "<value-from-ASTRAFLOW_PUBLIC_KEY>",
      "Region"     : "cn-bj2",
      "Signature"  : "<value-from-ASTRAFLOW_SIGNATURE>"
  }'

The calling method for the Xingtu management API is exactly the same, except that Action is replaced with Xingtu's own command (such as CreateUMInferAPIKey), and the business parameters are replaced with the parameters required by that command.

Determine the Region

UCloud's platform-wide list of regions (33 regions in total):

Region short ID Region name
cn-bj1 North China (Beijing)
cn-bj2 North China (Beijing 2)
cn-wlcb North China (Ulanqab)
cn-wlcb2 North China (Ulanqab 2)
cn-sh2 East China (Shanghai 2)
cn-jx East China (Jiaxing)
cn-sh Finance Cloud - East China (Shanghai)
cn-gd2 South China (Guangzhou 2)
cn-gd South China (Guangzhou)
cn-guiyang1 Southwest China (Guiyang)
hk Hong Kong
tw-tp Taiwan (Taipei)
sg Singapore
jpn-tky Japan (Tokyo)
kr-seoul South Korea (Seoul)
th-bkk Thailand (Bangkok)
idn-jakarta Indonesia (Jakarta)
vn-sng Vietnam (Ho Chi Minh)
ph-mnl Philippines (Manila)
ind-mumbai India (Mumbai)
pk-khi Pakistan (Karachi)
us-den United States (Denver)
us-ca United States (Los Angeles)
us-ws United States (Washington)
bra-saopaulo Brazil (São Paulo)
rus-mosc Russia (Moscow)
ge-fra Germany (Frankfurt)
uk-london United Kingdom (London)
uae-dubai United Arab Emirates (Dubai)
afr-nigeria Nigeria (Lagos)
uz-tas Uzbekistan (Tashkent)
kz-ala Kazakhstan (Almaty)
mx-mex Mexico (Mexico City)

Note: This is UCloud's platform-wide list of regions. Xingtu/UModelVerse services are not necessarily available in all regions. It is known that at least some Xingtu management API (such as ListUMInferRequestLogs) documentation explicitly states "you can first call ListUMInferRegions to get the available regions," which indicates that Xingtu maintains its own subset of available regions. If the user is unsure which regions Xingtu services can actually use, prioritize suggesting:

  1. First call ListUMInferRegions(one of the Xingtu management APIs) to get the list of regions available to the current account, and then let the user choose from them;
  2. If that API cannot be called for the time being, fall back to referring to the region codes in the table above, but explain to the user that this is only UCloud's general region list and does not mean that Xingtu services have been enabled in that region.

Common Xingtu/UModelVerse-related regions include cn-wlcb(Ulanqab) and us-ca(Los Angeles). When uncertain, confirm with the user and do not choose on the user's behalf.

Determine the ProjectId

If the user is unclear about their ProjectId, call the management API GetProjectList to get the list of projects under the account. This API itselfdoes not require Region/ProjectId, only the standard public parameters:

Parameter Type Required Description
Action string Yes Fixed to GetProjectList
PublicKey string Yes user public key
Signature string Yes calculate according to the algorithm above
IsFinance string No Whether it is a financial account (Yes/No). Generally, no need to fill it in.

Fields of interest in the response:

Field Type Description
RetCode int 0 indicates success
ProjectCount int Total number of items
ProjectSet array Item list, each item contains ProjectId、ProjectName、IsDefault(whether it is the default project) and other fields

After getting the list, display both ProjectId and ProjectName to the user and let the user confirm which project to use. Do not automatically choose for the user (unless the user explicitly says "use the default project"; in that case, you may select the item where IsDefault=true is true).

Detailed specification of the Star Map Management API

references/ The directory contains detailed request/response parameter specifications for the 21 currently confirmed existing Star Map Management APIs (one separate file per interface, named consistently with the snake_case corresponding to the Action). Before calling a specific interface, first open the corresponding file to confirm its business parameters, required fields, and response structure. Do not rely on impressions or copy parameter assumptions from other interfaces—even interfaces in the same group may have subtle parameter differences (for example, whetherRegionis required, whether array parameters have the.Nsuffix, etc.).

Inference API Key management:

Order and billing management:

Model plaza query:

Inference request logs:

The above list may be incomplete (for example, ListUMInferRegions mentioned in the documentation does not appear on the index page and has not yet been included). Index page address:https://astraflow.ucloud.cn/reference/modelverse. When new interfaces are discovered, add them under references/ using the same template.

Known questionable points in the documentation itself

During the organization process, several inconsistencies in the official documentation were found that engineers need to pay attention to during real calls. All have been annotated item by item in the "Response Fields" or "Examples" sections of the corresponding files. They are listed here in summary for quick location:

  • CreateUMInferAPIKey / ListUMInferAPIKey: In the response field table, Data should be a APIKey object (or its array), but in the response example given in the documentation, Data is rendered as a string/empty object, which does not match the field type.
  • ListUMInferRequestLogs: There is an extra top-level field in the response example that is not listed in the field table, TotalCount。
  • ListUFSquareModelFiltersAuth: The response field documentation itself only provides RetCode/Action/Message three generic fields, without any specific filter condition data structure; suspect the documentation has omissions.
  • GetFilterOptions: In the response example, multiple array[...] type fields (such as PricingSKUs、ProductCodes、Projects、Regions) are rendered as bare strings or empty objects, which do not match the types in the field table.
  • GetOrderAmount: The response example is missing TotalOrderAmount, which the field table marks as required, and has an extra top-level Data(empty object, meaning unknown) not recorded in the field table; in addition, this API's OrganizationIds.N type is string, which is inconsistent with the int type of the parameter with the same name in several other order APIs.
  • ListUnpaidOrderSummary：OrderTypes parameter does not have the .N suffix, which is inconsistent with the array notation of the parameter with the same name in the other order APIs (OrderTypes.N).
  • StartPayUnpaidOrders: The response field Results is documented as a single PayResult object reference rather than an array, but according to the semantics of "batch pay multiple orders", one result should be returned for each order number; suspect the documentation is incorrect; in the response example, Results is also just an empty object.

The above are allwording issues in the original documentation itself; this skill only records them faithfully and does not make subjective corrections; during actual integration testing, the real returned results should prevail, and if the documentation is indeed found to be wrong, it is recommended to report it to the AstraFlow platform documentation maintainers.

The operation process for calling a specific AstraFlow management API

  1. Confirm that PublicKey、PrivateKey、Region(if required by this API), andProjectId(if required by this API) have been obtained.
  2. Open the file corresponding to the target references/ under the Action directory, and confirm exactly which business parameters it requires (not every API needs Region, for example, GetProjectList does not need it; refer to that file specifically, and do not copy the parameter assumptions of other APIs). If the API is not yet in references/ , go to the index page https://astraflow.ucloud.cn/reference/modelverse to find it and add it following the same template.
  3. Assemble the complete parameter set (common parameters + business parameters), calculate Signature。
  4. according to the above algorithm, send the request, check RetCode, and when it is nonzero, troubleshoot the issue according to Message .
  5. If you suspect it is a signature issue, check first: whether parameters are missing, whether the sorting is correct, and whetherPrivateKey is placed at the end of the concatenated string and is not sent out as a parameter.