Create an qiyaov Platform Service Application

An "Application" represents the current account's subscription relationship to a service—you must apply first before you can create API credentials for this application and call business APIs. When applying for a service for the first time, the Application will receive the service's currently configured free_amount; this value may be 0.

ℹ️ This API belongs to the qiyaov Platform Management API, with the unified prefix https://api17.platform.acedata.cloud/api/v1/. For the complete API index, see Get the qiyaov Platform Document List.

Complete Integration Process

New users usually follow these 5 steps from registration to successfully calling their first business API:

  1. Obtain an account token → Manage qiyaov Platform Account Tokens
  2. Choose a service → Get the qiyaov Platform Service List
  3. Create an application (this document) → Obtain the initial quota according to the service configuration
  4. Create API credentials → Create qiyaov Platform API Credentials
  5. Call business APIs → Use the obtained 32-character Token to call https://api.qiyaov.com/<path>

API Overview

Item Content
Method POST
URL https://api17.platform.acedata.cloud/api/v1/applications/
Authentication ✅ Account token required
Content-Type application/json

Authentication Instructions (How to Obtain an Account Token)

Request header:

Authorization: Bearer ${PLATFORM_TOKEN}

An account token (Account Token) is an "account-level key" that developers use to manage their own account resources through APIs. How to obtain it:

  1. One-click creation in the console (recommended): Log in to the qiyaov Platform → Account Token Console → Click "Create" to obtain a token starting with platform-v1-.
  2. API creation: Use an existing account token or browser login session JWT to call POST /api/v1/platform-tokens/. For details, see Manage qiyaov Platform Account Tokens.

⚠️ Account tokens are as sensitive as passwords. Do not write them into frontend code or public repositories. If leaked, immediately delete and recreate them in the console.

Request Body

Parameter Type Required Description
service_id UUID ✅ The ID of the service to apply for. It can be obtained from items[].id in the service list

Request Examples

cURL

curl -X POST 'https://api17.platform.acedata.cloud/api/v1/applications/' \
  -H 'accept: application/json' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{"service_id": "38ecf158-36f2-42f2-8e7f-6786cdfc2452"}'

Python

import os
import requests

PLATFORM_TOKEN = os.environ["PLATFORM_TOKEN"]
SERVICE_ID = "38ecf158-36f2-42f2-8e7f-6786cdfc2452"

resp = requests.post(
    "https://api17.platform.acedata.cloud/api/v1/applications/",
    headers={
        "accept": "application/json",
        "authorization": f"Bearer {PLATFORM_TOKEN}",
        "content-type": "application/json",
    },
    json={"service_id": SERVICE_ID},
    timeout=10,
)

if resp.status_code == 201:
    app = resp.json()
    print(f"申请成功！application_id={app['id']}")
    print(f"初始额度：{app['remaining_amount']} {app.get('service', {}).get('unit', '')}")
elif resp.status_code == 400 and resp.json().get("code") == "duplication":
    print("⚠️ 已经申请过此服务，请到 /applications/ 列表里找到现成的 application_id")
else:
    print(f"申请失败：HTTP {resp.status_code} - {resp.text}")

Node.js

const PLATFORM_TOKEN = process.env.PLATFORM_TOKEN
const SERVICE_ID = '38ecf158-36f2-42f2-8e7f-6786cdfc2452'

const resp = await fetch('https://api17.platform.acedata.cloud/api/v1/applications/', {
  method: 'POST',
  headers: {
    accept: 'application/json',
    authorization: `Bearer ${PLATFORM_TOKEN}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({ service_id: SERVICE_ID }),
})

if (resp.status === 201) {
  const app = await resp.json()
  console.log('application_id =', app.id)
} else {
  console.error(await resp.text())
}

Response Examples

Success (HTTP 201)

{
  "id": "82f57141-2323-4453-8730-60f7d833a2da",
  "service_id": "38ecf158-36f2-42f2-8e7f-6786cdfc2452",
  "remaining_amount": 1.0,
  "used_amount": 0.0,
  "paid": false,
  "user_id": "89518d07-5560-4b05-92c1-667f3ddf6a4b",
  "disabled": false,
  "allow_consume_global": false,
  "scope": "Individual",
  "type": "Usage",
  "expired_at": null,
  "tags": null,
  "metadata": null,
  "client_ip": null,
  "client_fingerprint": null,
  "created_at": "2026-04-26T07:52:27.462400Z",
  "updated_at": "2026-04-26T07:52:27.462400Z"
}

The returned field structure is consistent with Get qiyaov Platform Service Application Details.

Already Applied For (HTTP 400)

{
  "detail": "Item already exists.",
  "code": "duplication",
  "trace_id": "1a87524f8cbba0b790b2951e2e43117e"
}

This is a hard limitation by design: each user can only have one Application for each service. If it already exists, find the existing one through Get the qiyaov Platform Service Application List.

Service Does Not Exist (HTTP 404)

{
  "detail": "Service not found.",
  "code": "not_found",
  "trace_id": "..."
}

Service Requires Review (HTTP 403)

{
  "detail": "This service requires manual verification.",
  "code": "need_verify",
  "trace_id": "..."
}

If the service has need_verify=true (this field can be seen in the service list), you need to apply for whitelisting through the ticket process.

Error Handling

HTTP code Meaning
400 duplication The service has already been requested by the current account
400 invalid service_id is missing or incorrectly formatted
401 not_authenticated The account token is missing or has been deleted
403 need_verify The service requires review; please follow the ticket process
404 not_found The service does not exist or has been taken offline

Unified error response format:

{
  "detail": "...",
  "code": "...",
  "trace_id": "..."
}

Practical Tips

  • Creation itself does not incur charges: Upon first creation, the initial quota is set according to the service's current free_amount; this value may be 0, and creating the same type of Application again does not guarantee repeated free credits.
  • Check the paid field to determine whether payment is required: When first requested, paid=false; it becomes true after payment is completed by calling Create qiyaov Platform Top-up Order.
  • disabled=true indicates temporary disablement—for example, due to risk control triggers, overdue payments, etc. When disabled, business APIs will return 403.
  • Do not create with unbounded concurrency: First obtain the target service_id from the paginated service list, then request them one by one as needed by the business; when encountering duplication, reuse the existing Application.