> ## 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 # Create a standalone campaign > Ad Campaigns. Can spend money or change spend: needs the ads:spend scope and X-Aisa-Confirm: spend; without the header the request is refused with confirmation_required and nothing is sent. Creates a campaign on the ad platform; with a budget and an active status it starts spending. validateOnly=true checks the request without acting and needs no confirmation. Creates an empty campaign, paused, so you can add ad sets and ads to it afterwards. Creates a campaign WITHOUT its first ad set / ad, on the platform of the given `connectionId`. Ad sets join it later via `existingCampaignId` on the create endpoints. Created `PAUSED` (TikTok `DISABLE`) unless `status: ACTIVE` where the platform supports it. 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 ## 请求规范 * **方法与路径:** POST /apis/v1/ads/campaigns * **可用状态:** enabled * **请求 URL 模板:** `https://api.aisa.one/apis/v1/ads/campaigns` * **connectionId:** query; 必填 * **X-Aisa-Confirm:** header; 可选 * **Idempotency-Key:** header; 可选 * **Runtime 事实版本:** fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09 [完整 OpenAPI 定义](https://aisa.one/docs/reference-contracts/zh/aisa-ads.json) 有效请求与价格声明（包括认证和引用的 schema）： ```json theme={null} { "operationId": "post_aisa_ads_apis_v1_ads_campaigns", "method": "POST", "path": "/apis/v1/ads/campaigns", "servers": [ { "url": "https://api.aisa.one" } ], "parameters": [ { "description": "The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead.", "in": "query", "name": "connectionId", "required": true, "schema": { "pattern": "^adc_[0-9A-Za-z]+$", "type": "string" } }, { "description": "Required with the value \"spend\" when the request can spend money or change spend. Without it the request is refused with 409 confirmation_required, which describes what would happen; nothing is sent to the ad platform.", "in": "header", "name": "X-Aisa-Confirm", "required": false, "schema": { "enum": [ "spend" ], "type": "string" } }, { "description": "Passed to the ad platform integration: a retry with the same key returns the first result instead of acting twice. AIsa never retries a write for you.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 191, "minLength": 1, "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "example": { "adAccountId": "act_757082720485182", "buyingType": "AUCTION", "connectionId": "adc_7f3k2m9q", "goal": "app_promotion", "isSkadnetworkAttribution": true, "name": "iOS app campaign", "promotedObject": { "applicationId": "123456789", "objectStoreUrl": "https://apps.apple.com/us/app/id123456789" }, "status": "PAUSED", "validateOnly": true }, "schema": { "additionalProperties": true, "properties": { "adAccountId": { "description": "Platform ad account id (Meta act_, Google customer id, LinkedIn account id, ...).", "type": "string" }, "bidAmount": { "description": "Whole currency units (USD: 5 = $5.00). Required for LOWEST_COST_WITH_BID_CAP and COST_CAP; ignored otherwise. Meta: validated here but NOT stored, since the campaign object only has bid_strategy.", "type": "number" }, "bidStrategy": { "description": "Campaign bid strategy. Meta stores `bid_strategy` alongside the budget, so this REQUIRES `budgetAmount` + `budgetType` on the same request (400 without a campaign budget).", "enum": [ "LOWEST_COST_WITHOUT_CAP", "LOWEST_COST_WITH_BID_CAP", "COST_CAP", "LOWEST_COST_WITH_MIN_ROAS" ], "type": "string" }, "budgetAmount": { "description": "Campaign-level (CBO) budget in WHOLE currency units (USD: 50 = $50.00), NOT cents. Meta's own Marketing API takes this same number in minor units, so it is an easy and expensive mix-up. Requires budgetType.", "type": "number" }, "budgetType": { "enum": [ "daily", "lifetime" ], "type": "string" }, "buyingType": { "description": "Every platform buys at auction by default, so this only needs sending on Meta, and only to choose RESERVED. `AUCTION` is accepted on every platform and changes nothing.", "enum": [ "AUCTION", "RESERVED" ], "type": "string" }, "connectionId": { "description": "The ads connection (adc_...), when not sent as the connectionId query parameter.", "pattern": "^adc_[0-9A-Za-z]+$", "type": "string" }, "endDate": { "description": "Reddit only (400 elsewhere). Campaign end (ISO 8601); a value without an offset is read in the ad account time zone. Requires a campaign budget (400 otherwise), and is required for `budgetType: lifetime`.", "format": "date-time", "type": "string" }, "goal": { "description": "Mapped to the ODAX objective (same mapping as POST /apis/v1/ads/create).", "enum": [ "engagement", "traffic", "awareness", "video_views", "lead_generation", "lead_conversion", "job_applicants", "conversions", "app_promotion", "catalog_sales", "page_likes", "page_visits" ], "type": "string" }, "isSkadnetworkAttribution": { "description": "Meta app promotion only. Immutable campaign flag. Set true for iOS 14+ SKAdNetwork campaigns and supply promotedObject.applicationId plus promotedObject.objectStoreUrl. The campaign receives promotedObject only when this flag is true.", "type": "boolean" }, "locationTargetingType": { "description": "Google only (400 elsewhere). Written on the new campaign.", "enum": [ "presence", "presence_or_interest" ], "type": "string" }, "manualCpc": { "additionalProperties": false, "description": "Google Search and Display only. Manual CPC bidding. Enhanced CPC is not offered: Google no longer lets Search and Display campaigns enable it. Exclusive with every other strategy field.", "properties": { "maxCpc": { "description": "Max CPC of the ad groups, in the account's currency units: set on the ad group created with the campaign, and on every ad group of the campaign when an update switches it to Manual CPC. Google gives an ad group without one a 0.01 bid.", "exclusiveMinimum": 0, "type": "number" } }, "required": [ "maxCpc" ], "type": "object" }, "name": { "maxLength": 255, "type": "string" }, "networkSettings": { "additionalProperties": false, "description": "Google Search campaigns only. Which networks the campaign serves on besides Google Search.", "properties": { "displayNetwork": { "description": "campaign.network_settings.target_content_network (Search with Display expansion)", "type": "boolean" }, "searchPartners": { "description": "campaign.network_settings.target_search_network", "type": "boolean" } }, "type": "object" }, "portfolioBidStrategyId": { "description": "Google only. Attach an existing portfolio bid strategy (numeric id from GET /apis/v1/ads/bid-strategies) to the new campaign instead of a standard one. Exclusive with bidStrategy.", "pattern": "^\\d+$", "type": "string" }, "promotedObject": { "additionalProperties": false, "description": "What the ad optimises against. Behaviour depends on the platform. Platforms other than Meta, TikTok, OpenAI and Reddit ignore `promotedObject` entirely. Meta: forwarded to the ad set's `promoted_object` (snake-cased).", "properties": { "applicationId": { "description": "App ID. Required for `goal: app_promotion`.", "type": "string" }, "customConversionId": { "description": "Custom Conversion ID, when optimising against one instead of a standard event. Accepted alone by this API, without `pixelId` or `customEventType`.", "type": "string" }, "customEventStr": { "description": "Meta only. Pixel custom-event name to optimise against (Meta's `custom_event_str`), exactly as it appears in Events Manager and your CAPI payloads (case-sensitive, not uppercased).", "type": "string" }, "customEventType": { "description": "The event the campaign/ad group optimises against. Meta: a standard event like `PURCHASE`, `LEAD`, `COMPLETE_REGISTRATION`, `ADD_TO_CART`. Uppercased internally, so any case works. Required for `goal: conversions`.", "type": "string" }, "objectStoreUrl": { "description": "App Store / Play Store listing URL. Required for `goal: app_promotion`.", "format": "uri", "type": "string" }, "offlineConversionDataSetId": { "description": "Meta only. Offline event set (dataset) to optimise toward. Post-merger these are datasets: the id is the dataset id (for pixel-backed datasets, the pixel id).", "type": "string" }, "pageId": { "description": "Facebook Page ID. Used by `goal: lead_generation`. Auto-filled from the connected Page when omitted.", "type": "string" }, "pixelId": { "description": "Pixel ID. Meta: Facebook Pixel ID, required for `goal: conversions`.", "type": "string" }, "productCatalogId": { "description": "Optional catalog ID. A catalog ID cannot replace productSetId.", "type": "string" }, "productSetId": { "description": "Meta product SET ID, for example from GET /apis/v1/ads/catalogs/{catalogId}/product-sets. Creating catalog ads needs only ads_management on the Meta login, not catalog_management. Where it goes.", "type": "string" }, "whatsappPhoneNumber": { "description": "Meta only. WhatsApp number on messaging-destination ad sets.", "type": "string" } }, "type": "object" }, "roasAverageFloor": { "description": "Decimal ROAS multiplier (2.0 = 2.0x). Required for LOWEST_COST_WITH_MIN_ROAS.", "type": "number" }, "specialAdCategories": { "items": { "enum": [ "HOUSING", "EMPLOYMENT", "CREDIT", "ISSUES_ELECTIONS_POLITICS", "FINANCIAL_PRODUCTS_SERVICES", "ONLINE_GAMBLING_AND_GAMING" ], "type": "string" }, "type": "array" }, "startDate": { "description": "Reddit only (400 elsewhere). Campaign start (ISO 8601); a value without an offset is read in the ad account time zone. Requires a campaign budget (`budgetAmount` + `budgetType`, 400 otherwise). Defaults to now.", "format": "date-time", "type": "string" }, "status": { "default": "PAUSED", "enum": [ "ACTIVE", "PAUSED" ], "type": "string" }, "targetImpressionShare": { "additionalProperties": false, "description": "Google Search only. Target impression share bidding. Exclusive with bidStrategy, portfolioBidStrategyId and manualCpc; bidAmount is refused alongside it (the ceiling is maxCpc).", "properties": { "location": { "enum": [ "ANYWHERE_ON_PAGE", "TOP_OF_PAGE", "ABSOLUTE_TOP_OF_PAGE" ], "type": "string" }, "maxCpc": { "description": "Max CPC bid limit, in the account's currency units. Google requires it.", "exclusiveMinimum": 0, "type": "number" }, "percent": { "description": "Target share of impressions, in percent (65 = 65%). Sent to Google as location_fraction_micros (1% = 10,000).", "exclusiveMinimum": 0, "maximum": 100, "type": "number" } }, "required": [ "location", "maxCpc", "percent" ], "type": "object" }, "validateOnly": { "description": "Meta and ChatGPT (OpenAI). Runs campaign validation without creating or persisting a campaign; Idempotency-Key storage is bypassed. Returns HTTP 200 with validateOnly true and status VALIDATED.", "type": "boolean" } }, "required": [ "adAccountId", "goal", "name" ], "type": "object" } } }, "required": true }, "x-aisa-status": "enabled", "x-aisa-pricing": { "description": "Ads operations are free. Ad spend is billed by the ad platform to the connected ad account, never by AIsa.", "kind": "no_customer_charge" }, "components": { "securitySchemes": { "bearerAuth": { "scheme": "bearer", "type": "http" } } } } ``` ## 费用与请求规则 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 公开参考值不是你的账户报价或最终扣费。对于支持 X-AISA-Cost-Mode: quote 的接口，执行前请针对完整请求获取免费报价；执行后通过响应费用元数据和 Usage Logs 核对结算费用。1 USD 等于 1,000,000 个整数 micro-USD。 ## OpenAPI ````yaml reference-contracts/zh/aisa-ads.json POST /apis/v1/ads/campaigns openapi: 3.1.0 info: description: '' title: AIsa Ads version: '1' x-aisa-capabilities: idempotency: Idempotency-Key max_price: X-AISA-Max-Price-USD quote: header: X-AISA-Cost-Mode value: quote x-aisa-configured-paths: [] x-aisa-document: facts_hash: fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09 generator_version: '3' protocol_version: '1' schema_version: '1' composer_version: '27' response_pending: [] document_hash: sha256:ba353f59e89e1ebabe0e301d8ef57d3cbfa6bb406a8c591ee9c3833d64b60520 x-aisa-plans: builder: 1 display_plan: payg payg: 1 similarweb_payg: 1 team: 1 version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb x-aisa-provider: aisa-ads x-aisa-catalogs: aisa-ads: title: AIsa Ads description: '' x-aisa-document: facts_hash: fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09 generator_version: '3' protocol_version: '1' schema_version: '1' x-aisa-plans: builder: 1 display_plan: payg payg: 1 similarweb_payg: 1 team: 1 version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb x-aisa-capabilities: idempotency: Idempotency-Key max_price: X-AISA-Max-Price-USD quote: header: X-AISA-Cost-Mode value: quote servers: - url: https://api.aisa.one security: - bearerAuth: [] paths: /apis/v1/ads/campaigns: post: summary: Create a standalone campaign description: >- Ad Campaigns. Can spend money or change spend: needs the ads:spend scope and X-Aisa-Confirm: spend; without the header the request is refused with confirmation_required and nothing is sent. Creates a campaign on the ad platform; with a budget and an active status it starts spending. validateOnly=true checks the request without acting and needs no confirmation. Creates an empty campaign, paused, so you can add ad sets and ads to it afterwards. Creates a campaign WITHOUT its first ad set / ad, on the platform of the given `connectionId`. Ad sets join it later via `existingCampaignId` on the create endpoints. Created `PAUSED` (TikTok `DISABLE`) unless `status: ACTIVE` where the platform supports it. 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 operationId: post_aisa_ads_apis_v1_ads_campaigns parameters: - description: >- The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead. in: query name: connectionId required: true schema: pattern: ^adc_[0-9A-Za-z]+$ type: string - description: >- Required with the value "spend" when the request can spend money or change spend. Without it the request is refused with 409 confirmation_required, which describes what would happen; nothing is sent to the ad platform. in: header name: X-Aisa-Confirm required: false schema: enum: - spend type: string - description: >- Passed to the ad platform integration: a retry with the same key returns the first result instead of acting twice. AIsa never retries a write for you. in: header name: Idempotency-Key required: false schema: maxLength: 191 minLength: 1 type: string requestBody: content: application/json: example: adAccountId: act_757082720485182 buyingType: AUCTION connectionId: adc_7f3k2m9q goal: app_promotion isSkadnetworkAttribution: true name: iOS app campaign promotedObject: applicationId: '123456789' objectStoreUrl: https://apps.apple.com/us/app/id123456789 status: PAUSED validateOnly: true schema: additionalProperties: true properties: adAccountId: description: >- Platform ad account id (Meta act_, Google customer id, LinkedIn account id, ...). type: string bidAmount: description: >- Whole currency units (USD: 5 = $5.00). Required for LOWEST_COST_WITH_BID_CAP and COST_CAP; ignored otherwise. Meta: validated here but NOT stored, since the campaign object only has bid_strategy. type: number bidStrategy: description: >- Campaign bid strategy. Meta stores `bid_strategy` alongside the budget, so this REQUIRES `budgetAmount` + `budgetType` on the same request (400 without a campaign budget). enum: - LOWEST_COST_WITHOUT_CAP - LOWEST_COST_WITH_BID_CAP - COST_CAP - LOWEST_COST_WITH_MIN_ROAS type: string budgetAmount: description: >- Campaign-level (CBO) budget in WHOLE currency units (USD: 50 = $50.00), NOT cents. Meta's own Marketing API takes this same number in minor units, so it is an easy and expensive mix-up. Requires budgetType. type: number budgetType: enum: - daily - lifetime type: string buyingType: description: >- Every platform buys at auction by default, so this only needs sending on Meta, and only to choose RESERVED. `AUCTION` is accepted on every platform and changes nothing. enum: - AUCTION - RESERVED type: string connectionId: description: >- The ads connection (adc_...), when not sent as the connectionId query parameter. pattern: ^adc_[0-9A-Za-z]+$ type: string endDate: description: >- Reddit only (400 elsewhere). Campaign end (ISO 8601); a value without an offset is read in the ad account time zone. Requires a campaign budget (400 otherwise), and is required for `budgetType: lifetime`. format: date-time type: string goal: description: >- Mapped to the ODAX objective (same mapping as POST /apis/v1/ads/create). enum: - engagement - traffic - awareness - video_views - lead_generation - lead_conversion - job_applicants - conversions - app_promotion - catalog_sales - page_likes - page_visits type: string isSkadnetworkAttribution: description: >- Meta app promotion only. Immutable campaign flag. Set true for iOS 14+ SKAdNetwork campaigns and supply promotedObject.applicationId plus promotedObject.objectStoreUrl. The campaign receives promotedObject only when this flag is true. type: boolean locationTargetingType: description: Google only (400 elsewhere). Written on the new campaign. enum: - presence - presence_or_interest type: string manualCpc: additionalProperties: false description: >- Google Search and Display only. Manual CPC bidding. Enhanced CPC is not offered: Google no longer lets Search and Display campaigns enable it. Exclusive with every other strategy field. properties: maxCpc: description: >- Max CPC of the ad groups, in the account's currency units: set on the ad group created with the campaign, and on every ad group of the campaign when an update switches it to Manual CPC. Google gives an ad group without one a 0.01 bid. exclusiveMinimum: 0 type: number required: - maxCpc type: object name: maxLength: 255 type: string networkSettings: additionalProperties: false description: >- Google Search campaigns only. Which networks the campaign serves on besides Google Search. properties: displayNetwork: description: >- campaign.network_settings.target_content_network (Search with Display expansion) type: boolean searchPartners: description: campaign.network_settings.target_search_network type: boolean type: object portfolioBidStrategyId: description: >- Google only. Attach an existing portfolio bid strategy (numeric id from GET /apis/v1/ads/bid-strategies) to the new campaign instead of a standard one. Exclusive with bidStrategy. pattern: ^\d+$ type: string promotedObject: additionalProperties: false description: >- What the ad optimises against. Behaviour depends on the platform. Platforms other than Meta, TikTok, OpenAI and Reddit ignore `promotedObject` entirely. Meta: forwarded to the ad set's `promoted_object` (snake-cased). properties: applicationId: description: 'App ID. Required for `goal: app_promotion`.' type: string customConversionId: description: >- Custom Conversion ID, when optimising against one instead of a standard event. Accepted alone by this API, without `pixelId` or `customEventType`. type: string customEventStr: description: >- Meta only. Pixel custom-event name to optimise against (Meta's `custom_event_str`), exactly as it appears in Events Manager and your CAPI payloads (case-sensitive, not uppercased). type: string customEventType: description: >- The event the campaign/ad group optimises against. Meta: a standard event like `PURCHASE`, `LEAD`, `COMPLETE_REGISTRATION`, `ADD_TO_CART`. Uppercased internally, so any case works. Required for `goal: conversions`. type: string objectStoreUrl: description: >- App Store / Play Store listing URL. Required for `goal: app_promotion`. format: uri type: string offlineConversionDataSetId: description: >- Meta only. Offline event set (dataset) to optimise toward. Post-merger these are datasets: the id is the dataset id (for pixel-backed datasets, the pixel id). type: string pageId: description: >- Facebook Page ID. Used by `goal: lead_generation`. Auto-filled from the connected Page when omitted. type: string pixelId: description: >- Pixel ID. Meta: Facebook Pixel ID, required for `goal: conversions`. type: string productCatalogId: description: >- Optional catalog ID. A catalog ID cannot replace productSetId. type: string productSetId: description: >- Meta product SET ID, for example from GET /apis/v1/ads/catalogs/{catalogId}/product-sets. Creating catalog ads needs only ads_management on the Meta login, not catalog_management. Where it goes. type: string whatsappPhoneNumber: description: >- Meta only. WhatsApp number on messaging-destination ad sets. type: string type: object roasAverageFloor: description: >- Decimal ROAS multiplier (2.0 = 2.0x). Required for LOWEST_COST_WITH_MIN_ROAS. type: number specialAdCategories: items: enum: - HOUSING - EMPLOYMENT - CREDIT - ISSUES_ELECTIONS_POLITICS - FINANCIAL_PRODUCTS_SERVICES - ONLINE_GAMBLING_AND_GAMING type: string type: array startDate: description: >- Reddit only (400 elsewhere). Campaign start (ISO 8601); a value without an offset is read in the ad account time zone. Requires a campaign budget (`budgetAmount` + `budgetType`, 400 otherwise). Defaults to now. format: date-time type: string status: default: PAUSED enum: - ACTIVE - PAUSED type: string targetImpressionShare: additionalProperties: false description: >- Google Search only. Target impression share bidding. Exclusive with bidStrategy, portfolioBidStrategyId and manualCpc; bidAmount is refused alongside it (the ceiling is maxCpc). properties: location: enum: - ANYWHERE_ON_PAGE - TOP_OF_PAGE - ABSOLUTE_TOP_OF_PAGE type: string maxCpc: description: >- Max CPC bid limit, in the account's currency units. Google requires it. exclusiveMinimum: 0 type: number percent: description: >- Target share of impressions, in percent (65 = 65%). Sent to Google as location_fraction_micros (1% = 10,000). exclusiveMinimum: 0 maximum: 100 type: number required: - location - maxCpc - percent type: object validateOnly: description: >- Meta and ChatGPT (OpenAI). Runs campaign validation without creating or persisting a campaign; Idempotency-Key storage is bypassed. Returns HTTP 200 with validateOnly true and status VALIDATED. type: boolean required: - adAccountId - goal - name type: object required: true responses: '200': content: application/json: schema: properties: adAccountId: type: string campaignId: const: '' description: Empty because no campaign was created. type: string objective: type: string status: const: VALIDATED type: string validateOnly: description: Always true. type: boolean type: object description: Campaign validation passed without creating a campaign. '201': content: application/json: schema: properties: adAccountId: type: string campaignId: description: Platform id of the new campaign type: string objective: description: Resolved ODAX objective (e.g. OUTCOME_SALES). type: string status: enum: - ACTIVE - PAUSED type: string type: object description: Campaign created default: content: application/json: schema: properties: error: properties: code: type: - string - 'null' details: additionalProperties: {} type: - object - 'null' message: type: - string - 'null' param: type: - string - 'null' retryHint: type: - string - 'null' retryable: type: - boolean - 'null' type: type: - string - 'null' type: - object - 'null' type: object description: Error. The code field is stable; see the error catalog. components: securitySchemes: bearerAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.