> ## 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

# 查找相似达人

> 查找指定平台上与参考账号相似的推荐达人，排除参考账号；相似分数保留来源原始含义。

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

## 计费

| 输入 | 计价单位 | 价格 (USD) |
| - | - | - |
| /input/platform = bilibili | 每条实际交付结果 | 0.001 |
| /input/platform = douyin | 每条实际交付结果 | 0.001 |
| /input/platform = instagram | 每条实际交付结果 | 0.12 |
| /input/platform = tiktok | 每条实际交付结果 | 0.0166 |
| /input/platform = xiaohongshu | 每条实际交付结果 | 0.0167 |
| /input/platform = youtube | 每条实际交付结果 | 0.0166 |

仅表内参数值有价格；未列出的值不会回退到基础价格。
执行时按 `ceil(/input/limit / 1)` 个单位预扣，最多 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.find_similar
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.find_similar:
    post:
      tags:
        - 任务
      summary: 查找相似达人
      description: 查找指定平台上与参考账号相似的推荐达人，排除参考账号；相似分数保留来源原始含义。
      operationId: task_creators.find_similar
      parameters:
        - name: Idempotency-Key
          in: header
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/creators.find_similar_request'
      responses:
        '200':
          description: 成功交付或正常查空
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/creators.find_similar_response'
        default:
          description: 错误；以实际 HTTP 状态和重试指引为准
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/creators.find_similar_error'
components:
  schemas:
    creators.find_similar_request:
      $ref: '#/components/schemas/creators.find_similar_request.6_Request'
      $schema: https://json-schema.org/draft/2020-12/schema
      x-aisa-runtime-rules:
        exactly_one:
          - - profile_url
            - handle
            - native_id
        requires:
          id_namespace:
            - native_id
          native_id:
            - id_namespace
    creators.find_similar_response:
      $ref: '#/components/schemas/creators.find_similar_response.6_Response'
      $schema: https://json-schema.org/draft/2020-12/schema
      x-aisa-runtime-rules:
        exactly_one:
          - - profile_url
            - handle
            - native_id
        requires:
          id_namespace:
            - native_id
          native_id:
            - id_namespace
    creators.find_similar_error:
      $ref: '#/components/schemas/creators.find_similar_error.0_Error'
      $schema: https://json-schema.org/draft/2020-12/schema
    creators.find_similar_request.6_Request:
      additionalProperties: false
      properties:
        input:
          $ref: '#/components/schemas/creators.find_similar_request.5_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:
                        - ''
                        - merge
                      type: string
                    - type: 'null'
              type: object
            - type: 'null'
      required:
        - input
      type: object
    creators.find_similar_response.6_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.find_similar_response.7_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.find_similar_response.7_Result'
            - type: 'null'
        status:
          enum:
            - found
            - partial
            - not_found
          type: string
        task:
          const: creators.find_similar
        version:
          const: 1
      required:
        - task
        - version
        - status
        - result
        - meta
      type: object
    creators.find_similar_error.0_Error:
      additionalProperties: false
      properties:
        error:
          $ref: '#/components/schemas/creators.find_similar_error.1_ErrorDetail'
      required:
        - error
      type: object
    creators.find_similar_request.5_Input:
      additionalProperties: false
      allOf:
        - oneOf:
            - properties:
                profile_url:
                  not:
                    type: 'null'
              required:
                - profile_url
            - properties:
                handle:
                  not:
                    type: 'null'
              required:
                - handle
            - properties:
                native_id:
                  not:
                    type: 'null'
              required:
                - native_id
        - if:
            properties:
              id_namespace:
                not:
                  type: 'null'
            required:
              - id_namespace
          then:
            allOf:
              - properties:
                  native_id:
                    not:
                      type: 'null'
                required:
                  - native_id
        - if:
            properties:
              native_id:
                not:
                  type: 'null'
            required:
              - native_id
          then:
            allOf:
              - properties:
                  id_namespace:
                    not:
                      type: 'null'
                required:
                  - id_namespace
        - if:
            properties:
              platform:
                enum:
                  - instagram
            required:
              - platform
          then:
            properties:
              handle:
                anyOf:
                  - pattern: ^@?[A-Za-z0-9._]+$
                    type: string
                  - type: 'null'
              profile_url:
                anyOf:
                  - format: uri
                    not:
                      pattern: >-
                        ^https://(www\.)?instagram\.com/([pP]|[rR][eE][eE][lL][sS]?|[sS][tT][oO][rR][iI][eE][sS]|[eE][xX][pP][lL][oO][rR][eE]|[aA][cC][cC][oO][uU][nN][tT][sS]|[dD][iI][rR][eE][cC][tT])/?$
                    pattern: ^https://(www\.)?instagram\.com/[A-Za-z0-9._]+/?$
                    type: string
                  - type: 'null'
        - if:
            properties:
              platform:
                enum:
                  - instagram
            required:
              - platform
          then:
            properties:
              id_namespace:
                anyOf:
                  - enum:
                      - instagram.user
                    type: string
                  - type: 'null'
        - if:
            properties:
              platform:
                enum:
                  - tiktok
            required:
              - platform
          then:
            properties:
              handle:
                anyOf:
                  - pattern: ^@?[A-Za-z0-9._]+$
                    type: string
                  - type: 'null'
              profile_url:
                anyOf:
                  - format: uri
                    pattern: ^https://(www\.)?tiktok\.com/@[A-Za-z0-9._]+/?$
                    type: string
                  - type: 'null'
        - if:
            properties:
              platform:
                enum:
                  - tiktok
            required:
              - platform
          then:
            properties:
              id_namespace:
                anyOf:
                  - enum:
                      - tiktok.sec_uid
                    type: string
                  - type: 'null'
        - if:
            properties:
              platform:
                enum:
                  - youtube
            required:
              - platform
          then:
            properties:
              handle:
                anyOf:
                  - pattern: ^@?[A-Za-z0-9._-]+$
                    type: string
                  - type: 'null'
              profile_url:
                anyOf:
                  - format: uri
                    pattern: >-
                      ^https://(www\.)?youtube\.com/(@[A-Za-z0-9._-]+|channel/UC[A-Za-z0-9_-]{22})/?$
                    type: string
                  - type: 'null'
        - if:
            properties:
              platform:
                enum:
                  - youtube
            required:
              - platform
          then:
            allOf:
              - not:
                  properties:
                    native_id:
                      not:
                        type: 'null'
                  required:
                    - native_id
              - not:
                  properties:
                    id_namespace:
                      not:
                        type: 'null'
                  required:
                    - id_namespace
        - if:
            properties:
              platform:
                enum:
                  - douyin
            required:
              - platform
          then:
            allOf:
              - not:
                  properties:
                    profile_url:
                      not:
                        type: 'null'
                  required:
                    - profile_url
              - not:
                  properties:
                    handle:
                      not:
                        type: 'null'
                  required:
                    - handle
        - if:
            properties:
              platform:
                enum:
                  - douyin
            required:
              - platform
          then:
            properties:
              id_namespace:
                anyOf:
                  - enum:
                      - douyin.user
                      - xingtu.author
                    type: string
                  - type: 'null'
            required:
              - native_id
              - id_namespace
        - if:
            properties:
              platform:
                enum:
                  - xiaohongshu
            required:
              - platform
          then:
            allOf:
              - not:
                  properties:
                    profile_url:
                      not:
                        type: 'null'
                  required:
                    - profile_url
              - not:
                  properties:
                    handle:
                      not:
                        type: 'null'
                  required:
                    - handle
        - if:
            properties:
              platform:
                enum:
                  - xiaohongshu
            required:
              - platform
          then:
            properties:
              id_namespace:
                anyOf:
                  - enum:
                      - xiaohongshu.user
                    type: string
                  - type: 'null'
            required:
              - native_id
              - id_namespace
        - if:
            properties:
              platform:
                enum:
                  - bilibili
            required:
              - platform
          then:
            allOf:
              - not:
                  properties:
                    profile_url:
                      not:
                        type: 'null'
                  required:
                    - profile_url
              - not:
                  properties:
                    handle:
                      not:
                        type: 'null'
                  required:
                    - handle
        - if:
            properties:
              platform:
                enum:
                  - bilibili
            required:
              - platform
          then:
            properties:
              id_namespace:
                anyOf:
                  - enum:
                      - bilibili.mid
                    type: string
                  - type: 'null'
            required:
              - native_id
              - id_namespace
        - if:
            properties:
              id_namespace:
                enum:
                  - instagram.user
                  - douyin.user
                  - xingtu.kol
                  - xingtu.author
                  - bilibili.mid
            required:
              - id_namespace
          then:
            properties:
              native_id:
                pattern: ^[1-9][0-9]*$
                type: string
      properties:
        handle:
          anyOf:
            - description: >-
                Account handle, not a display name or URL; choose exactly one of
                profile_url, handle or native_id.
              maxLength: 256
              pattern: \S
              type: string
            - type: 'null'
        id_namespace:
          anyOf:
            - description: >-
                Namespace of native_id; must be paired with native_id and match
                the selected platform.
              enum:
                - instagram.user
                - tiktok.sec_uid
                - douyin.user
                - xingtu.author
                - xiaohongshu.user
                - bilibili.mid
              type: string
            - type: 'null'
        limit:
          anyOf:
            - default: 20
              description: >-
                Maximum distinct accounts after merging and excluding the
                reference account.
              maximum: 100
              minimum: 1
              type: integer
            - type: 'null'
        native_id:
          anyOf:
            - description: >-
                Native account ID as a string in the paired id_namespace;
                accepted namespaces depend on platform.
              maxLength: 256
              pattern: \S
              type: string
            - type: 'null'
        platform:
          description: >-
            Platform shared by the reference account and all returned similar
            accounts.
          enum:
            - instagram
            - tiktok
            - youtube
            - douyin
            - xiaohongshu
            - bilibili
          type: string
        profile_url:
          anyOf:
            - description: >-
                HTTPS account profile URL on the selected platform; choose
                exactly one of profile_url, handle or native_id.
              maxLength: 2048
              pattern: \S
              type: string
            - type: 'null'
      required:
        - platform
      type: object
    creators.find_similar_response.7_Result:
      additionalProperties: false
      properties:
        items:
          items:
            allOf:
              - $ref: >-
                  #/components/schemas/creators.find_similar_response.2_CreatorSimilarItem
              - allOf:
                  - anyOf:
                      - properties:
                          creator:
                            properties:
                              identity:
                                properties:
                                  native_id:
                                    minItems: 1
                                    minProperties: 1
                                    not:
                                      type: 'null'
                                    pattern: \S
                                required:
                                  - native_id
                                type: object
                            required:
                              - identity
                            type: object
                        required:
                          - creator
                        type: object
                      - properties:
                          creator:
                            properties:
                              identity:
                                properties:
                                  handle:
                                    minItems: 1
                                    minProperties: 1
                                    not:
                                      type: 'null'
                                    pattern: \S
                                required:
                                  - handle
                                type: object
                            required:
                              - identity
                            type: object
                        required:
                          - creator
                        type: object
                      - properties:
                          creator:
                            properties:
                              identity:
                                properties:
                                  profile_url:
                                    minItems: 1
                                    minProperties: 1
                                    not:
                                      type: 'null'
                                    pattern: \S
                                required:
                                  - profile_url
                                type: object
                            required:
                              - identity
                            type: object
                        required:
                          - creator
                        type: object
          minItems: 1
          type: array
      required:
        - items
      type: object
    creators.find_similar_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.find_similar_response.2_CreatorSimilarItem:
      additionalProperties: false
      properties:
        creator:
          $ref: '#/components/schemas/creators.find_similar_response.3_CreatorSummary'
        matches:
          items:
            allOf:
              - $ref: >-
                  #/components/schemas/creators.find_similar_response.1_CreatorMatch
              - properties:
                  type:
                    enum:
                      - provider_recommendation
                required:
                  - type
          minItems: 1
          type: array
      required:
        - creator
        - matches
      type: object
    creators.find_similar_response.3_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.find_similar_response.0_CreatorIdentity
      required:
        - identity
        - display_name
        - avatar_url
        - follower_count
      type: object
    creators.find_similar_response.1_CreatorMatch:
      additionalProperties: false
      properties:
        provider_rank:
          anyOf:
            - minimum: 1
              type: integer
            - type: 'null'
        provider_score:
          anyOf:
            - type: number
            - type: 'null'
        score_scale:
          anyOf:
            - type: string
            - type: 'null'
        type:
          enum:
            - search_match
            - provider_recommendation
          type: string
      required:
        - type
        - provider_rank
        - provider_score
        - score_scale
      type: object
    creators.find_similar_response.0_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
            - douyin
            - xiaohongshu
            - bilibili
          type: string
        profile_url:
          anyOf:
            - format: uri
              type: string
            - type: 'null'
      required:
        - platform
        - native_id
        - id_namespace
        - handle
        - profile_url
      type: object
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````

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