> ## 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) |
| - | - | - |
| 所有有效输入 | 每条实际交付结果 | 0.12 |

执行时按 `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.search
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.search:
    post:
      tags:
        - 任务
      summary: 搜索达人
      description: 按内容方向与受支持的筛选条件搜索达人。每个来源必须应用全部请求条件，否则不参与调用。
      operationId: task_creators.search
      parameters:
        - name: Idempotency-Key
          in: header
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/creators.search_request'
      responses:
        '200':
          description: 成功交付或正常查空
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/creators.search_response'
        default:
          description: 错误；以实际 HTTP 状态和重试指引为准
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/creators.search_error'
components:
  schemas:
    creators.search_request:
      $ref: '#/components/schemas/creators.search_request.6_Request'
      $schema: https://json-schema.org/draft/2020-12/schema
      x-aisa-runtime-rules:
        at_least_one:
          - - query
            - followers_min
            - followers_max
            - creator_countries
        ordered_pairs:
          - - followers_min
            - followers_max
    creators.search_response:
      $ref: '#/components/schemas/creators.search_response.6_Response'
      $schema: https://json-schema.org/draft/2020-12/schema
      x-aisa-runtime-rules:
        at_least_one:
          - - query
            - followers_min
            - followers_max
            - creator_countries
        ordered_pairs:
          - - followers_min
            - followers_max
    creators.search_error:
      $ref: '#/components/schemas/creators.search_error.0_Error'
      $schema: https://json-schema.org/draft/2020-12/schema
    creators.search_request.6_Request:
      additionalProperties: false
      properties:
        input:
          $ref: '#/components/schemas/creators.search_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.search_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.search_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.search_response.7_Result'
            - type: 'null'
        status:
          enum:
            - found
            - partial
            - not_found
          type: string
        task:
          const: creators.search
        version:
          const: 1
      required:
        - task
        - version
        - status
        - result
        - meta
      type: object
    creators.search_error.0_Error:
      additionalProperties: false
      properties:
        error:
          $ref: '#/components/schemas/creators.search_error.1_ErrorDetail'
      required:
        - error
      type: object
    creators.search_request.5_Input:
      additionalProperties: false
      allOf:
        - anyOf:
            - properties:
                query:
                  not:
                    type: 'null'
              required:
                - query
            - properties:
                followers_min:
                  not:
                    type: 'null'
              required:
                - followers_min
            - properties:
                followers_max:
                  not:
                    type: 'null'
              required:
                - followers_max
            - properties:
                creator_countries:
                  not:
                    type: 'null'
              required:
                - creator_countries
        - if:
            properties:
              platform:
                enum:
                  - tiktok
                  - youtube
            required:
              - platform
          then:
            properties:
              query:
                not:
                  type: 'null'
            required:
              - query
        - if:
            properties:
              creator_countries:
                not:
                  type: 'null'
            required:
              - creator_countries
          then:
            anyOf:
              - allOf:
                  - not:
                      properties:
                        platform:
                          not:
                            type: 'null'
                      required:
                        - platform
              - properties:
                  platform:
                    enum:
                      - instagram
                      - tiktok
                      - youtube
                required:
                  - platform
        - if:
            allOf:
              - properties:
                  creator_countries:
                    not:
                      type: 'null'
                required:
                  - creator_countries
              - not:
                  properties:
                    query:
                      not:
                        type: 'null'
                  required:
                    - query
          then:
            properties:
              creator_countries:
                items:
                  const: US
              platform:
                enum:
                  - instagram
                  - null
      properties:
        creator_countries:
          anyOf:
            - description: >-
                V1 verified value subset, not a complete country list; see
                platform and query conditions in the final contract.
              items:
                enum:
                  - US
                  - GB
                type: string
              maxItems: 1
              minItems: 1
              type: array
            - type: 'null'
        followers_max:
          anyOf:
            - description: >-
                Inclusive maximum follower count; must be at least followers_min
                when both are provided.
              maximum: 1000000000000
              minimum: 0
              type: integer
            - type: 'null'
        followers_min:
          anyOf:
            - description: Inclusive minimum follower count; omitted means no lower bound.
              maximum: 1000000000000
              minimum: 0
              type: integer
            - type: 'null'
        limit:
          anyOf:
            - default: 20
              description: >-
                Maximum number of distinct delivered accounts across all
                selected sources and platforms.
              maximum: 100
              minimum: 1
              type: integer
            - type: 'null'
        platform:
          anyOf:
            - description: >-
                Optional platform. When omitted, select eligible platforms and
                sources that apply every requested filter.
              enum:
                - instagram
                - tiktok
                - youtube
                - douyin
                - xiaohongshu
                - bilibili
              type: string
            - type: 'null'
        query:
          anyOf:
            - description: >-
                Content topic or niche keyword; not an account name or a shared
                category ID.
              maxLength: 50
              pattern: \S
              type: string
            - type: 'null'
      type: object
    creators.search_response.7_Result:
      additionalProperties: false
      properties:
        items:
          items:
            allOf:
              - $ref: >-
                  #/components/schemas/creators.search_response.2_CreatorSearchItem
              - 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.search_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.search_response.2_CreatorSearchItem:
      additionalProperties: false
      properties:
        creator:
          $ref: '#/components/schemas/creators.search_response.3_CreatorSummary'
        matches:
          items:
            allOf:
              - $ref: '#/components/schemas/creators.search_response.1_CreatorMatch'
              - properties:
                  type:
                    enum:
                      - search_match
                required:
                  - type
          minItems: 1
          type: array
      required:
        - creator
        - matches
      type: object
    creators.search_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.search_response.0_CreatorIdentity'
      required:
        - identity
        - display_name
        - avatar_url
        - follower_count
      type: object
    creators.search_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.search_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.