astraflow-api

AstraFlow プラットフォーム管理API呼び出しガイド

AstraFlow（AstraFlow）は、UCloudが企業向けに提供する専用AI開発プラットフォームです。その中のモデルサービスサブプラットフォームは UModelVerse です。このスキルでは管理API（API Keyの管理、請求・注文、モデル広場の照会、推論ログの照会など）のみを対象とします。つまり、ドキュメント内の https://astraflow.ucloud.cn/reference/modelverse/ にあるAPI群です。

まず確認：管理API ≠ モデル呼び出しAPI

AstraFlow プラットフォームには、実際にはまったく異なる2種類のAPI体系があります。混同しないでください。

1. モデル呼び出しAPI（OpenAI/Gemini互換API。例：POST https://api.modelverse.cn/v1/chat/completions）：大規模言語モデルを実際に呼び出して推論するためのAPIです。認証方法は簡単で、API Keyをリクエストヘッダー Authorization: Bearer {api_key} に入れるだけです。署名計算は不要です。このAPI Keyは、コンソールの https://console.ucloud.cn/modelverse/experience/api-keys で作成できます。
2. 管理API（本スキルの対象。例：CreateUMInferAPIKey、ListUMInferRequestLogs）：アカウント配下のリソースを管理するためのAPIです。たとえば、上記の推論用API Keyの作成・削除、注文や請求の照会、モデル広場のデータや推論ログの照会などを行います。このAPI体系では、UCloud共通API体系のPublicKey/PrivateKey署名認証を使用します。UCloudのクラウドホストやクラウドディスクなど、従来の製品ラインのAPIと同じ認証方式であり、「モデル呼び出しAPI」のBearer Token認証とはまったく異なります。

以降の内容はすべて、2つ目の管理APIを対象とします。

呼び出し前に必要な4つのパラメーター

AstraFlowの管理APIを呼び出すには、次の4つのパラメーターがすべて必須です。

パラメーター	説明
Region	ビジネスリージョン。例：cn-wlcb。リクエストをどのリージョンのサービスにルーティングするかを決定します
ProjectId	プロジェクトID。アカウントに複数のプロジェクトがある場合、リソースの所属先を区別するために使用します。省略すると、デフォルトでメインアカウントのデフォルトプロジェクトが使われますが、サブアカウントでは必ず指定してください
PublicKey	UCloudアカウントの公開鍵です。署名計算とリクエスト自体の両方で必要なパラメーターです
PrivateKey	UCloudアカウントの秘密鍵です。ローカルでの署名計算にのみ使われ、リクエストパラメーターには含まれず、サーバーにも送信されません

PublicKey/PrivateKey は、UCloudコンソールの「API密钥管理」ページで取得します（アカウントレベルのキーであり、上記のモデル呼び出しAPI Keyではありません）。

ユーザーにこれら4つのパラメーターを尋ねる方法

• ユーザーがまだ提供していない場合は、ユーザーに直接尋ねるか、環境変数で指定できることを案内してください。次の変数名を推奨します（現在のプロジェクトに既定の命名規則がない場合の推奨名です。実際の名前はユーザーやプロジェクトの慣習に合わせて変更できます）。

export ASTRAFLOW_PUBLIC_KEY="<public-key>"
export ASTRAFLOW_PRIVATE_KEY="<private-key>"
export ASTRAFLOW_REGION="cn-wlcb"
export ASTRAFLOW_PROJECT_ID="<project-id>"

• PrivateKey は高度な機密情報です。ローカルでの署名計算にのみ使用し、ユーザーへの応答、ログ、生成したコードリポジトリ内のファイル、コミット履歴に絶対に含めないでください。これを使うスクリプトを実行する前に、set -x など、変数値を出力するデバッグ設定が有効になっていないことを確認してください。
• ユーザーがどの Region を選べばよいかわからない場合は、以下の「Regionの決定」セクションを参照してください。
• ユーザーがどの ProjectId を使えばよいかわからない場合は、以下の「ProjectIdの決定」セクションを参照してください。

リクエストの基本形式

• リクエスト先：https://api.ucloud.cn（UCloud共通ゲートウェイです。実際にどのバックエンドサービスにルーティングされるかは、リクエスト内の Action パラメーターによって決まります）
• GET または POST をサポートします。POST の場合は Content-Type: application/json を使用します。
• すべてのリクエストに、以下の3つの「共通パラメーター」を含める必要があります。これはすべてのUCloud APIに共通する要件です。

パラメーター	型	必須	説明
Action	string	はい	APIの指令名。例：CreateUMInferAPIKey、ListUMInferAPIKey
PublicKey	string	はい	ユーザーの公開鍵
Signature	string	はい	公開鍵、秘密鍵、および今回のリクエストの全パラメーターから計算した署名です。次のセクションを参照してください

共通パラメーターに加えて、各 Action の業務パラメーター（Region、ProjectId、および各API固有のパラメーターなど）も指定します。

• レスポンスはJSON形式で、共通レスポンスフィールドは次のとおりです。

フィールド	型	説明
RetCode	int	0は成功、0以外は失敗を示します
Action	string	対応するリクエストの指令名です
Message	string	RetCode が0以外の場合、失敗の原因を示します

呼び出しに失敗した場合は、まず RetCode/Message を確認してください。よくある問題は、170 署名がない、171 署名エラー、160/161 Action がない、または存在しない、292 プロジェクトが存在しない、294 アクセス元IPが拒否された、などです。署名関連のエラーが発生した場合は、まずパラメーターの並び順、パラメーターの漏れがないか、PrivateKey が正しいかを確認してください。

Signatureの計算方法

Signature は、PublicKey、PrivateKey、および今回のリクエストのすべてのパラメーター（Signature 自体を除く）から計算します。アルゴリズムはSHA1で、手順は次のとおりです。

1. 今回のリクエストで送信するすべてのパラメーター（共通パラメーターの Action、PublicKey、すべての業務パラメーター。例：Region、ProjectId、各API固有のパラメーター）を集めます。ただし、Signature 自体は含めません。
2. これらのパラメーターを、パラメーター名で昇順に並べ替えます（ASCII順）。
3. 並べ替えた順に、各パラメーターの「パラメーター名」と「パラメーター値」を連結し、1つの文字列にします。HTTPエスケープは行いません（URLエンコードしないでください）。
4. 連結した文字列の末尾に PrivateKey を追加します。
5. 文字列全体をSHA1でハッシュ化します。得られた16進数の文字列（小文字）が Signature の値です。

エンコードの詳細：

• ブール値はリテラル true / false にエンコードします。
• 浮動小数点数の小数部分が0の場合は、整数部分のみを残します（例：42.0 は 42 とします）。
• 浮動小数点数は指数表記にしないでください。
• 配列型のパラメーター（例：ModelNames.N）は、展開後の実際のキー名（ModelNames.0、ModelNames.1 など）を使用して、並べ替えと連結を行います。

安全な例（プレースホルダーと環境変数のみを使用し、使用可能なキーをドキュメントに記載しません）：

• PublicKey：ASTRAFLOW_PUBLIC_KEY から読み取ります。
• PrivateKey：ASTRAFLOW_PRIVATE_KEY からのみ読み取ります。コマンドのリテラル、ログ、リポジトリ内のファイルには記載しません。
• リクエストパラメーター：Action=DescribeUHostInstance、Region=cn-bj2、Limit=10。

シェルを使ってローカルで署名を計算し、結果を環境変数に保存します（実行前に set -x が有効になっていないことを確認してください）。

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

Signatureを計算したら、通常のパラメーターとして最終リクエストに追加し、他のパラメーターと一緒に送信します。

リクエスト例

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>"
  }'

AstraFlow管理APIの呼び出し方法はまったく同じです。Action をAstraFlow独自の指令（例：CreateUMInferAPIKey）に置き換え、業務パラメーターをその指令で必要なパラメーターに置き換えてください。

确定 Region

UCloud全平台的地域列表（共33个地域）：

地域短ID	地域名称
cn-bj1	华北（北京）
cn-bj2	华北（北京2）
cn-wlcb	华北（乌兰察布）
cn-wlcb2	华北（乌兰察布2）
cn-sh2	华东（上海2）
cn-jx	华东（嘉兴）
cn-sh	金融云-华东（上海）
cn-gd2	华南（广州2）
cn-gd	华南（广州）
cn-guiyang1	西南（贵阳）
hk	香港
tw-tp	台湾（台北）
sg	新加坡
jpn-tky	日本（东京）
kr-seoul	韩国（首尔）
th-bkk	泰国（曼谷）
idn-jakarta	印度尼西亚（雅加达）
vn-sng	越南（胡志明）
ph-mnl	菲律宾（马尼拉）
ind-mumbai	印度（孟买）
pk-khi	巴基斯坦（卡拉奇）
us-den	美国（丹佛）
us-ca	美国（洛杉矶）
us-ws	美国（华盛顿）
bra-saopaulo	巴西（圣保罗）
rus-mosc	俄罗斯（莫斯科）
ge-fra	德国（法兰克福）
uk-london	英国（伦敦）
uae-dubai	阿联酋（迪拜）
afr-nigeria	尼日利亚（拉各斯）
uz-tas	乌兹别克斯坦（塔什干）
kz-ala	哈萨克斯坦（阿拉木图）
mx-mex	墨西哥（墨西哥城）

注意：这是UCloud全平台的地域列表，星图/UModelVerse服务不一定在所有地域都开通。已知至少部分星图管理API（如 ListUMInferRequestLogs）文档明确提示"可先调用 ListUMInferRegions 获取可选地域"，说明星图自己维护了一份可用地域子集。如果用户不确定星图业务实际能用哪些地域，优先建议：

1. 先调用 ListUMInferRegions（星图管理API之一）拿到当前账号可用的地域列表，再让用户从中选择；
2. 如果暂时无法调用该接口，退而参考上表中的地域码，但要向用户说明这只是UCloud通用地域列表，不代表星图服务已在该地域开通。

常见的星图/UModelVerse相关地域包括 cn-wlcb（乌兰察布）和 us-ca（洛杉矶），不确定时应向用户确认，不要替用户擅自选择。

确定 ProjectId

如果用户不清楚自己的 ProjectId，调用管理API GetProjectList 获取账号下的项目列表。这个接口本身不需要 Region/ProjectId，只需要标准的公共参数：

参数	类型	必填	说明
Action	string	是	固定为 GetProjectList
PublicKey	string	是	用户公钥
Signature	string	是	按上面的算法计算
IsFinance	string	否	是否财务账号（Yes/No），一般不用填

响应中关心的字段：

字段	类型	说明
RetCode	int	0表示成功
ProjectCount	int	项目总数
ProjectSet	array	项目列表，每项包含 ProjectId、ProjectName、IsDefault（是否默认项目）等字段

拿到列表后，把 ProjectId 和 ProjectName 都展示给用户，让用户确认要用哪个项目，不要替用户自动挑选（除非用户明确说"用默认项目"，这时可以选 IsDefault=true 的那一项）。

星图管理API详细规范

references/ 目录下收录了目前已确认存在的21个星图管理API的详细请求/响应参数规范（每个接口一个独立文件，命名与Action对应的snake_case一致）。调用某个具体接口前，先打开对应文件确认它的业务参数、必填项和响应结构，不要凭印象或照抄别的接口的参数假设——即使是同一分组下的接口，参数也可能有细微差异（比如是否需要Region、数组参数是否带.N后缀等）。

推理API Key管理：

• CreateUMInferAPIKey — 创建apikey
• DeleteUMInferAPIKey — 删除apikey
• UpdateUMInferAPIKey — 更新apikey
• ListUMInferAPIKey — 列表查询APIKey

订单与账单管理：

• DownloadListPaidOrders — 下载已完成订单明细
• DownloadListUnpaidOrders — 下载欠费订单明细
• DownloadOrderSummary — 下载订单汇总
• GetFilterOptions — 查询订单筛选选项
• GetOrderAmount — 查询订单汇总统计
• ListPaidOrderSummary — 查询已完成订单汇总
• ListPaidOrders — 查询已完成订单明细
• ListUnpaidOrderSummary — 查询欠费订单汇总
• ListUnpaidOrders — 查询欠费订单明细
• StartPayUnpaidOrders — 批量支付欠费订单（写操作，谨慎调用）

模型广场查询：

• GetUFSquareModelDetail — 获取广场模型详情
• GetUFSquareModelPrices — 批量查询模型价格
• ListUFSquareModel — 查询模型广场数据
• ListUFSquareModelFiltersAuth — 查询模型广场过滤条件

推理请求日志：

• DownloadUMInferRequestLog — 导出推理请求日志
• GetUMInferRequestLogDetail — 原始日志详情
• ListUMInferRequestLogs — 日志明细列表

以上列表可能不完整（例如文档中提到的 ListUMInferRegions 就未在索引页出现，尚未收录）。索引页地址：https://astraflow.ucloud.cn/reference/modelverse，发现新接口时按同样的模板在 references/ 下补充。

既知のドキュメント自体の不明点

整理の過程で、公式ドキュメントに実際に呼び出す際にエンジニアが注意すべき不整合がいくつか見つかりました。いずれも対応するファイルの「レスポンスフィールド」または「例」のセクションに個別に記載しています。すばやく確認できるよう、ここにまとめます。

• CreateUMInferAPIKey / ListUMInferAPIKey：レスポンスフィールドの表では Data は APIKey オブジェクト（またはその配列）であるはずですが、ドキュメントに記載されたレスポンス例では Data が文字列／空オブジェクトとして表示されており、フィールドの型と一致しません。
• ListUMInferRequestLogs：レスポンス例のトップレベルに、フィールド表に記載されていない TotalCount が余分に含まれています。
• ListUFSquareModelFiltersAuth：レスポンスフィールドのドキュメントには RetCode／Action／Message の3つの共通フィールドしか記載されておらず、具体的なフィルター条件のデータ構造がありません。ドキュメントの記載漏れと思われます。
• GetFilterOptions：レスポンス例では、複数の array[...] 型のフィールド（PricingSKUs、ProductCodes、Projects、Regions など）が、そのままの文字列または空オブジェクトとして表示されており、フィールド表の型と一致しません。
• GetOrderAmount：レスポンス例には、フィールド表で必須とされている TotalOrderAmount がなく、フィールド表に記載されていないトップレベルの Data（空オブジェクト、意味は不明）が余分に含まれています。また、このインターフェースの OrganizationIds.N の型は string で、ほかのいくつかの注文インターフェースにある同名のパラメーターの型 int と一致しません。
• ListUnpaidOrderSummary：OrderTypes パラメーターに .N サフィックスがなく、ほかのいくつかの注文インターフェースにある同名パラメーターの配列表記（OrderTypes.N）と一致しません。
• StartPayUnpaidOrders：レスポンスフィールド Results は、ドキュメントでは配列ではなく単一の PayResult オブジェクト参照として記載されています。しかし、「複数の注文を一括で支払う」という意味からすると、注文番号ごとに結果が1件返されるはずです。ドキュメントの記述に誤りがあると思われます。また、レスポンス例の Results も空オブジェクトにすぎません。

以上はすべて原文書自体の記述上の問題です。このスキルでは事実をそのまま記録するにとどめ、独自の修正は行いません。実際に連携する際は実際のレスポンスを基準にしてください。ドキュメントに誤りがあることが確認できた場合は、星図プラットフォームのドキュメント管理者に報告することをおすすめします。

特定の星図管理APIを呼び出す手順

1. PublicKey、PrivateKey、Region（このインターフェースで必要な場合）、ProjectId（このインターフェースで必要な場合）を取得済みであることを確認します。
2. references/ ディレクトリ内で、対象の Action に対応するファイルを開き、必要な業務パラメーターを確認します（すべてのインターフェースで Region が必要なわけではありません。たとえば、GetProjectList では不要です。具体的には該当ファイルを確認し、ほかのインターフェースのパラメーターに関する想定をそのまま当てはめないでください）。references/ に該当するインターフェースがない場合は、索引ページ https://astraflow.ucloud.cn/reference/modelverse で検索し、同じテンプレートに従って追加します。
3. 完全なパラメーター一式（共通パラメーター＋業務パラメーター）を組み立て、上記のアルゴリズムで Signature を計算します。
4. リクエストを送信し、RetCode を確認します。0以外の場合は Message を確認して問題を調査します。
5. 署名に問題があると思われる場合は、まずパラメーターの漏れや並び順が正しいか、PrivateKey が連結文字列の末尾にあり、リクエストパラメーターとして送信されていないかを確認します。