CartViral Static Ads API

openapi: 3.2.0
info:
  title: CartViral Static Ads API
  version: 1.0.0
  description: 'AI product videos for e-commerce: import products, generate TikTok, Reels and Shorts clips, get download links, and work with the CartViral Earn creator marketplace. Same operations as the MCP server at https://app.cartviral.com/mcp. Docs: https://cartviral.com/api'
  contact:
    name: CartViral
    email: support@cartviral.com
    url: https://cartviral.com
servers:
- url: https://app.cartviral.com/api/v1
security:
- bearer: []
- oauth:
  - mcp
tags:
- name: Static Ads
paths:
  /static-ads:
    post:
      operationId: generateStaticAds
      summary: Queue a static ad image set of a product
      description: 'Queue a set of static ad images (Meta, TikTok) for one catalog product, built from its own photos with exact text, never an invented claim, fake discount or review: 4 credits per set no matter how many templates are picked, each template rendered at 3 sizes (1:1, 4:5, 9:16). Templates: price_offer (Leads with the real price - a discount only when you enter one.); benefit_callouts (Three benefits straight from your product facts, nothing invented.); us_vs_them (A side-by-side comparison - never names a competitor.); problem_solution (Names the buyer''s problem, then the product as the fix.); sticky_note (A handwritten-style native note over your product photo.); feature_closeup (A zoomed-in detail with labelled pointers to what matters.). Leave templates out to get all 6 of them. Credits are charged from the account; a failed set refunds automatically. Poll list_static_ads for download links.'
      x-openai-isConsequential: true
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Invalid input or the action could not be done; body has an error message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid credentials
        '429':
          description: 'Rate limit: 120 calls per minute per key'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                product_id:
                  type: string
                  description: Product id from list_products
                templates:
                  type: array
                  items:
                    type: string
                    enum:
                    - price_offer
                    - benefit_callouts
                    - us_vs_them
                    - problem_solution
                    - sticky_note
                    - feature_closeup
                  description: Optional subset of template ids (see this tool's description), up to 6; omit for all of them
              required:
              - product_id
      tags:
      - Static Ads
    get:
      operationId: listStaticAds
      summary: Static ad sets with render status and download links
      description: Recent static ad sets of the account's catalog, newest first, with render status, the ad copy CartViral wrote and, when done, a zip download link and each image's view/download link.
      x-openai-isConsequential: false
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 12
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Invalid input or the action could not be done; body has an error message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid credentials
        '429':
          description: 'Rate limit: 120 calls per minute per key'
      tags:
      - Static Ads
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: API key from Account → AI agents (cv_live_...), or an OAuth access token
    oauth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.cartviral.com/oauth/authorize
          tokenUrl: https://app.cartviral.com/oauth/token
          refreshUrl: https://app.cartviral.com/oauth/token
          scopes:
            mcp: Use your CartViral account