> ## Documentation Index
> Fetch the complete documentation index at: https://aisa.one/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> - Base URLs: models `https://api.aisa.one/v1` (Gemini GenerateContent: `https://api.aisa.one/v1beta`); data APIs `https://api.aisa.one/apis/v1`. The `servers` of each operation in https://aisa.one/openapi.yaml is authoritative.
> - Auth: `Authorization: Bearer $AISA_API_KEY`. Never print, log, or commit the key.
> - MCP (preferred for agents): `https://mcp.aisa.one/mcp`, signed in with OAuth, so there is no key to paste.
> - Agent Skill: `npx skills add AIsa-team/agent-skills --skill aisa`. Fallback with the AIsa CLI: `aisa skills install aisa`.
> - Spending: docs, https://aisa.one/models, https://aisa.one/api, `/v1/models`, and MCP `search`, `list_categories`, `get_details`, `batch_quote`, and the `account` operation are free. Quote the exact calls before running them (MCP `batch_quote`, CLI `aisa quote --json`). If the quote reports `auto_execute_eligible: true`, run it unless the user set a tighter limit or asked only for a quote. Otherwise, tell the user in one message the planned calls, the quoted price, and a total USD budget for the task, then wait for approval. Direct HTTP calls follow the stricter rule at https://aisa.one/docs/get-started/cli.md#direct-http-fallback. Do not make paid calls to test availability. Full rule: https://aisa.one/llms.txt

# 获取达人榜单

> 查询指定市场与周期的一份达人榜单。榜单身份必须一致，GMV、热度与直播间榜单不能互相替代。

上方请求和响应面板使用此 API 发布的 Schema。条件必填和参数组合限制属于请求契约；组合筛选条件或账号身份前，请查看完整 Schema。

## 计费

| 输入 | 计价单位 | 价格 (USD) |
| - | - | - |
| /input/ranking\_key = bilibili.follower\_growth | 每次成功请求 | 0.02 |
| /input/ranking\_key = douyin.hot\_accounts.24h | 每次成功请求 | 0.0034 |
| /input/ranking\_key = tiktok\_shop.creator\_gmv.last7days | 每次成功请求 | 0.0734 |
| /input/ranking\_key = tiktok\_shop.creator\_gmv.monthly | 每 10 个请求单位 | 0.09859 |

仅表内参数值有价格；未列出的值不会回退到基础价格。
对于 tiktok\_shop.creator\_gmv.monthly：请求价格 = `ceil(/input/limit / 10) × 所选单价`，总额向上取整到 USD 0.0001 的倍数；请求数量上限 100。成功返回较少结果仍按请求数量计价。
成功交付才收费；正常查空不收费。

发送相同请求并带上 `X-AISA-Cost-Mode: quote`，获取与输入对应的报价；报价不执行任务，也不预扣资金。实际执行时预扣预计请求费用，按上述规则结算。用 `X-AISA-Max-Price-USD` 设置价格上限。

执行任务时使用 `Idempotency-Key`。错误时查看 `error.code`、`error.request_id`、`error.retryable` 和 `error.retry_hint`。提示先核对结算时，应先查询原请求再决定是否重试；不能把待结算当作已退款。


## OpenAPI

````yaml zh/tasks/openapi.json POST /v1/tasks/creators.get_rankings
openapi: 3.1.0
info:
  title: AIsa Tasks
  version: '1'
  x-aisa-runtime-release:
    artifact_revision: 79833298e5347cbf6f763bc9313cec8dbb21b3f99e3e4bff89628c9bd47f8bed
    compiler_revision: 66257d5d26817f3e6eddc90b34155367d96513e9
    source_digest: cde7dca0fddbeccf0b89ef7580ab640c42058405baae9a3a6854c95c7c2a370e
    generation: 15127
servers:
  - url: https://api.aisa.one
security:
  - bearer: []
paths:
  /v1/tasks/creators.get_rankings:
    post:
      tags:
        - 任务
      summary: 获取达人榜单
      description: 查询指定市场与周期的一份达人榜单。榜单身份必须一致，GMV、热度与直播间榜单不能互相替代。
      operationId: task_creators.get_rankings
      parameters:
        - name: Idempotency-Key
          in: header
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/creators.get_rankings_request'
      responses:
        '200':
          description: 成功交付或正常查空
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/creators.get_rankings_response'
        default:
          description: 错误；以实际 HTTP 状态和重试指引为准
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/creators.get_rankings_error'
components:
  schemas:
    creators.get_rankings_request:
      $ref: '#/components/schemas/creators.get_rankings_request.10_Request'
      $schema: https://json-schema.org/draft/2020-12/schema
      x-aisa-runtime-rules: {}
    creators.get_rankings_response:
      $ref: '#/components/schemas/creators.get_rankings_response.10_Response'
      $schema: https://json-schema.org/draft/2020-12/schema
      x-aisa-runtime-rules: {}
    creators.get_rankings_error:
      $ref: '#/components/schemas/creators.get_rankings_error.0_Error'
      $schema: https://json-schema.org/draft/2020-12/schema
    creators.get_rankings_request.10_Request:
      additionalProperties: false
      properties:
        input:
          $ref: '#/components/schemas/creators.get_rankings_request.9_Input'
        options:
          anyOf:
            - additionalProperties: false
              properties:
                detail:
                  anyOf:
                    - enum:
                        - ''
                        - full
                      type: string
                    - type: 'null'
                max_providers:
                  anyOf:
                    - maximum: 8
                      minimum: 0
                      type: integer
                    - type: 'null'
                providers:
                  anyOf:
                    - additionalProperties: false
                      properties:
                        exclude:
                          anyOf:
                            - items:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                              type: array
                            - type: 'null'
                        only:
                          anyOf:
                            - items:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                              type: array
                            - type: 'null'
                      type: object
                    - type: 'null'
                strategy:
                  anyOf:
                    - enum:
                        - ''
                        - auto
                      type: string
                    - type: 'null'
              type: object
            - type: 'null'
      required:
        - input
      type: object
    creators.get_rankings_response.10_Response:
      additionalProperties: false
      allOf:
        - else:
            properties:
              meta:
                properties:
                  delivered:
                    const: false
              result:
                type: 'null'
          if:
            properties:
              status:
                enum:
                  - found
                  - partial
          then:
            properties:
              meta:
                properties:
                  delivered:
                    const: true
              result:
                $ref: '#/components/schemas/creators.get_rankings_response.11_Result'
      properties:
        meta:
          additionalProperties: false
          properties:
            approximate_fields:
              items:
                type: string
              type:
                - array
                - 'null'
            delivered:
              type: boolean
            missing_fields:
              additionalProperties:
                description: >-
                  A stable missing-field reason, or distinct reasons separated
                  by '; '. Unrecognized internal diagnostics are reported as
                  unspecified.
                pattern: >-
                  ^(not_returned|not_supported|unparseable|continuation_failed|reference_identity_unverifiable|page_limit_reached|report_part_failed|some_account_identities_unusable|pagination_not_reported|page_or_item_limit_reached|some_distributions_unusable|quote_not_usable|quote_availability_not_returned|quote_price_not_returned|unspecified)(;
                  (not_returned|not_supported|unparseable|continuation_failed|reference_identity_unverifiable|page_limit_reached|report_part_failed|some_account_identities_unusable|pagination_not_reported|page_or_item_limit_reached|some_distributions_unusable|quote_not_usable|quote_availability_not_returned|quote_price_not_returned|unspecified))*$
                type: string
              type:
                - object
                - 'null'
          required:
            - missing_fields
            - approximate_fields
            - delivered
          type: object
        result:
          anyOf:
            - $ref: '#/components/schemas/creators.get_rankings_response.11_Result'
            - type: 'null'
        status:
          enum:
            - found
            - partial
            - not_found
          type: string
        task:
          const: creators.get_rankings
        version:
          const: 1
      required:
        - task
        - version
        - status
        - result
        - meta
      type: object
    creators.get_rankings_error.0_Error:
      additionalProperties: false
      properties:
        error:
          $ref: '#/components/schemas/creators.get_rankings_error.1_ErrorDetail'
      required:
        - error
      type: object
    creators.get_rankings_request.9_Input:
      additionalProperties: false
      allOf:
        - if:
            properties:
              ranking_key:
                enum:
                  - tiktok_shop.creator_gmv.monthly
            required:
              - ranking_key
          then:
            properties:
              country:
                type: string
              period_value:
                pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$
                type: string
              platform:
                const: tiktok
            required:
              - country
              - period_value
        - if:
            properties:
              ranking_key:
                enum:
                  - tiktok_shop.creator_gmv.monthly
            required:
              - ranking_key
          then:
            else:
              properties:
                page:
                  anyOf:
                    - maximum: 5
                      type: integer
                    - type: 'null'
            if:
              properties:
                limit:
                  not:
                    type: 'null'
              required:
                - limit
            then:
              anyOf:
                - properties:
                    limit:
                      maximum: 1
                      type: integer
                    page:
                      anyOf:
                        - maximum: 100
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 2
                      type: integer
                    page:
                      anyOf:
                        - maximum: 50
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 3
                      type: integer
                    page:
                      anyOf:
                        - maximum: 33
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 4
                      type: integer
                    page:
                      anyOf:
                        - maximum: 25
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 5
                      type: integer
                    page:
                      anyOf:
                        - maximum: 20
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 6
                      type: integer
                    page:
                      anyOf:
                        - maximum: 16
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 7
                      type: integer
                    page:
                      anyOf:
                        - maximum: 14
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 8
                      type: integer
                    page:
                      anyOf:
                        - maximum: 12
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 9
                      type: integer
                    page:
                      anyOf:
                        - maximum: 11
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 10
                      type: integer
                    page:
                      anyOf:
                        - maximum: 10
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 11
                      type: integer
                    page:
                      anyOf:
                        - maximum: 9
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 12
                      type: integer
                    page:
                      anyOf:
                        - maximum: 8
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 14
                      type: integer
                    page:
                      anyOf:
                        - maximum: 7
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 16
                      type: integer
                    page:
                      anyOf:
                        - maximum: 6
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 20
                      type: integer
                    page:
                      anyOf:
                        - maximum: 5
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 25
                      type: integer
                    page:
                      anyOf:
                        - maximum: 4
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 33
                      type: integer
                    page:
                      anyOf:
                        - maximum: 3
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 50
                      type: integer
                    page:
                      anyOf:
                        - maximum: 2
                          type: integer
                        - type: 'null'
                - properties:
                    limit:
                      maximum: 100
                      type: integer
                    page:
                      anyOf:
                        - maximum: 1
                          type: integer
                        - type: 'null'
        - if:
            properties:
              ranking_key:
                enum:
                  - tiktok_shop.creator_gmv.last7days
            required:
              - ranking_key
          then:
            properties:
              country:
                enum:
                  - US
                  - GB
                  - TH
              limit:
                anyOf:
                  - minimum: 5
                  - type: 'null'
              page:
                anyOf:
                  - maximum: 5
                  - type: 'null'
              platform:
                const: tiktok
            required:
              - country
        - if:
            not:
              properties:
                ranking_key:
                  enum:
                    - tiktok_shop.creator_gmv.monthly
              required:
                - ranking_key
          then:
            allOf:
              - not:
                  properties:
                    period_value:
                      not:
                        type: 'null'
                  required:
                    - period_value
        - if:
            properties:
              ranking_key:
                enum:
                  - douyin.hot_accounts.24h
            required:
              - ranking_key
          then:
            allOf:
              - allOf:
                  - not:
                      properties:
                        country:
                          not:
                            type: 'null'
                      required:
                        - country
              - properties:
                  page:
                    anyOf:
                      - const: 1
                      - type: 'null'
                  platform:
                    const: douyin
        - if:
            properties:
              ranking_key:
                enum:
                  - bilibili.follower_growth
            required:
              - ranking_key
          then:
            allOf:
              - allOf:
                  - not:
                      properties:
                        country:
                          not:
                            type: 'null'
                      required:
                        - country
              - properties:
                  page:
                    anyOf:
                      - const: 1
                      - type: 'null'
                  platform:
                    const: bilibili
      properties:
        country:
          anyOf:
            - description: >-
                Ranking market; required for TikTok Shop boards and forbidden
                for Douyin and Bilibili. Last-7-days supports US, GB and TH.
              enum:
                - AT
                - BE
                - BR
                - DE
                - ES
                - FR
                - GB
                - ID
                - IT
                - JP
                - MX
                - MY
                - NL
                - PH
                - PL
                - PT
                - SG
                - TH
                - US
                - VN
              type: string
            - type: 'null'
        limit:
          anyOf:
            - default: 20
              description: >-
                Maximum items per page, not a guaranteed result count.
                Last-7-days requires 5-100; other boards allow 1-100.
              maximum: 100
              minimum: 1
              type: integer
            - type: 'null'
        page:
          anyOf:
            - default: 1
              description: >-
                Page number. Monthly requires page times limit <= 100;
                last-7-days allows 1-5; Douyin and Bilibili require 1.
              maximum: 1000
              minimum: 1
              type: integer
            - type: 'null'
        period_value:
          anyOf:
            - description: >-
                Month in YYYY-MM format; required for the monthly board and
                forbidden for all other boards.
              maxLength: 32
              pattern: \S
              type: string
            - type: 'null'
        platform:
          description: Platform of the ranking; must match ranking_key.
          enum:
            - tiktok
            - douyin
            - bilibili
          type: string
        ranking_key:
          description: >-
            Ranking identity, including its metric and period; selects one board
            and cannot fall back to a different board.
          enum:
            - tiktok_shop.creator_gmv.monthly
            - tiktok_shop.creator_gmv.last7days
            - douyin.hot_accounts.24h
            - bilibili.follower_growth
          type: string
      required:
        - platform
        - ranking_key
      type: object
    creators.get_rankings_response.11_Result:
      allOf:
        - $ref: >-
            #/components/schemas/creators.get_rankings_response.5_CreatorRankingResult
        - allOf:
            - properties:
                items:
                  minItems: 1
                  minProperties: 1
                  not:
                    type: 'null'
                  pattern: \S
              required:
                - items
              type: object
    creators.get_rankings_error.1_ErrorDetail:
      additionalProperties: false
      else:
        properties:
          retryable:
            const: false
      if:
        properties:
          retry_hint:
            const: after_delay
      properties:
        code:
          enum:
            - invalid_request
            - invalid_input
            - unsupported_route
            - unsupported_capability
            - unsupported_identity
            - provider_rejected_input
            - invalid_cost_mode
            - cost_quote_payment_unsupported
            - cost_quote_unsupported
            - unpriced_request_value
            - missing_api_key
            - invalid_api_key
            - api_key_disabled
            - expired_api_key
            - unauthorized
            - forbidden
            - user_disabled
            - ip_not_allowed
            - api_key_access_denied
            - estimated_price_exceeds_max_price
            - insufficient_api_key_balance
            - insufficient_wallet_balance
            - task_not_found
            - endpoint_not_found
            - request_in_progress
            - request_already_completed
            - idempotency_conflict
            - request_id_conflict
            - request_too_large
            - method_not_allowed
            - rate_limit_exceeded
            - internal_error
            - service_unavailable
          type: string
        message:
          type: string
        param:
          type: string
        problems:
          items:
            type: string
          type: array
        request_id:
          minLength: 1
          type: string
        retry_hint:
          enum:
            - never
            - after_delay
            - reconcile_first
          type: string
        retryable:
          type: boolean
        similar_tasks:
          items:
            type: string
          type: array
        task_id:
          type: string
      required:
        - code
        - message
        - request_id
        - retryable
        - retry_hint
      then:
        properties:
          retryable:
            const: true
      type: object
    creators.get_rankings_response.5_CreatorRankingResult:
      additionalProperties: false
      properties:
        has_more:
          anyOf:
            - type: boolean
            - type: 'null'
        items:
          anyOf:
            - items:
                $ref: >-
                  #/components/schemas/creators.get_rankings_response.3_CreatorRankedItem
              type: array
            - type: 'null'
        page:
          minimum: 1
          type: integer
        page_size:
          maximum: 100
          minimum: 1
          type: integer
        ranking:
          $ref: '#/components/schemas/creators.get_rankings_response.4_CreatorRanking'
        total:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
      required:
        - ranking
        - items
        - page
        - page_size
        - total
        - has_more
      type: object
    creators.get_rankings_response.3_CreatorRankedItem:
      additionalProperties: false
      properties:
        creator:
          $ref: '#/components/schemas/creators.get_rankings_response.6_CreatorSummary'
        metric_value:
          anyOf:
            - $ref: >-
                #/components/schemas/creators.get_rankings_response.0_CreatorCommerceMetric
            - type: 'null'
        native_rank:
          anyOf:
            - minimum: 1
              type: integer
            - type: 'null'
        position:
          anyOf:
            - minimum: 1
              type: integer
            - type: 'null'
      required:
        - creator
        - position
        - native_rank
        - metric_value
      type: object
    creators.get_rankings_response.4_CreatorRanking:
      additionalProperties: false
      properties:
        direction:
          anyOf:
            - enum:
                - asc
                - desc
              type: string
            - type: 'null'
        market:
          anyOf:
            - type: string
            - type: 'null'
        metric:
          anyOf:
            - enum:
                - gmv
                - follower_growth
              type: string
            - type: 'null'
        native_category:
          anyOf:
            - type: string
            - type: 'null'
        ranking_key:
          enum:
            - tiktok_shop.creator_gmv.monthly
            - tiktok_shop.creator_gmv.last7days
            - douyin.hot_accounts.24h
            - bilibili.follower_growth
          type: string
        window:
          $ref: '#/components/schemas/creators.get_rankings_response.7_CreatorWindow'
      required:
        - ranking_key
        - market
        - window
        - metric
        - direction
        - native_category
      type: object
    creators.get_rankings_response.6_CreatorSummary:
      additionalProperties: false
      properties:
        avatar_url:
          anyOf:
            - type: string
            - type: 'null'
        display_name:
          anyOf:
            - type: string
            - type: 'null'
        follower_count:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
        identity:
          $ref: >-
            #/components/schemas/creators.get_rankings_response.1_CreatorIdentity
      required:
        - identity
        - display_name
        - avatar_url
        - follower_count
      type: object
    creators.get_rankings_response.0_CreatorCommerceMetric:
      additionalProperties: false
      allOf:
        - if:
            properties:
              name:
                enum:
                  - gmv
            required:
              - name
          then:
            properties:
              unit:
                enum:
                  - currency
            required:
              - unit
        - if:
            not:
              properties:
                name:
                  enum:
                    - gmv
              required:
                - name
          then:
            properties:
              unit:
                enum:
                  - count
            required:
              - unit
        - if:
            not:
              properties:
                name:
                  enum:
                    - follower_growth
              required:
                - name
          then:
            properties:
              value:
                anyOf:
                  - minimum: 0
                  - type: 'null'
      oneOf:
        - properties:
            amount:
              type: 'null'
            unit:
              const: count
            value:
              type: number
        - properties:
            amount:
              type: object
            unit:
              const: currency
            value:
              type: 'null'
      properties:
        amount:
          anyOf:
            - $ref: >-
                #/components/schemas/creators.get_rankings_response.2_CreatorMoney
            - type: 'null'
        name:
          enum:
            - gmv
            - sales_count
            - product_count
            - follower_growth
          type: string
        scope:
          enum:
            - creator
            - product
          type: string
        unit:
          enum:
            - count
            - currency
          type: string
        value:
          anyOf:
            - type: number
            - type: 'null'
        window:
          $ref: '#/components/schemas/creators.get_rankings_response.7_CreatorWindow'
      required:
        - name
        - scope
        - value
        - amount
        - unit
        - window
      type: object
    creators.get_rankings_response.7_CreatorWindow:
      additionalProperties: false
      properties:
        days:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
        end:
          anyOf:
            - type: string
            - type: 'null'
        kind:
          enum:
            - snapshot
            - rolling
            - calendar
            - recent_posts
            - lifetime
            - unknown
          type: string
        label:
          anyOf:
            - type: string
            - type: 'null'
        start:
          anyOf:
            - type: string
            - type: 'null'
        timezone:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - kind
        - start
        - end
        - days
        - timezone
        - label
      type: object
    creators.get_rankings_response.1_CreatorIdentity:
      additionalProperties: false
      allOf:
        - else:
            properties:
              id_namespace:
                type: 'null'
          if:
            properties:
              native_id:
                type: string
          then:
            properties:
              id_namespace:
                minLength: 1
                type: string
      anyOf:
        - properties:
            native_id:
              minLength: 1
              type: string
        - properties:
            handle:
              minLength: 1
              type: string
        - properties:
            profile_url:
              minLength: 1
              type: string
      properties:
        handle:
          anyOf:
            - pattern: \S
              type: string
            - type: 'null'
        id_namespace:
          anyOf:
            - pattern: \S
              type: string
            - type: 'null'
        native_id:
          anyOf:
            - pattern: \S
              type: string
            - type: 'null'
        platform:
          enum:
            - instagram
            - tiktok
            - youtube
            - twitter
            - twitch
            - onlyfans
            - douyin
            - xiaohongshu
            - bilibili
            - facebook
            - snapchat
            - pinterest
            - linkedin
            - discord
          type: string
        profile_url:
          anyOf:
            - format: uri
              type: string
            - type: 'null'
      required:
        - platform
        - native_id
        - id_namespace
        - handle
        - profile_url
      type: object
    creators.get_rankings_response.2_CreatorMoney:
      additionalProperties: false
      properties:
        amount:
          pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$
          type: string
        currency:
          pattern: ^[A-Z]{3}$
          type: string
      required:
        - amount
        - currency
      type: object
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.