CartViral Create API

openapi: 3.2.0
info:
  title: CartViral Create 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: Create
paths:
  /create/options:
    get:
      operationId: getCreateOptions
      summary: 'Create: video models, frames, camera moves and prices'
      description: 'What the Create tools accept and cost: video models (our engine Gemini Omni Flash, plus premium models when switched on) with credits per length, frames, camera moves, brand film moods, and the price of every Create tool. Free.'
      x-openai-isConsequential: false
      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'
      tags:
      - Create
  /create/image:
    post:
      operationId: createImage
      summary: Images from your own prompt and reference photos (covers, banners, scenes)
      description: 'Images from your own prompt, optionally guided by up to 3 reference photos (a face, a product, a style, a layout): covers and YouTube thumbnails (use 16:9), banners, product scenes, posters. Not tied to the catalog. 1 credit per image, 1, 2 or 4 images. Poll list_creations.'
      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:
                prompt:
                  type: string
                  description: What to make, in any language. Say what each reference photo is for, e.g. 'the man from photo 1 shocked, the product from photo 2 in his hand, bold yellow title MY STORE MADE $10K'
                aspect:
                  type: string
                  enum:
                  - '9:16'
                  - '4:5'
                  - '1:1'
                  - '16:9'
                  default: '9:16'
                  description: 'Frame: 9:16 vertical (TikTok, Reels, Shorts), 4:5, 1:1, 16:9 (YouTube, covers, banners)'
                count:
                  type: integer
                  enum:
                  - 1
                  - 2
                  - 4
                  default: 1
                reference_images:
                  type: array
                  items:
                    type: string
                  maxItems: 3
                  description: 'Reference photos: CartViral /u/ links or public https file links, up to 3'
              required:
              - prompt
      tags:
      - Create
  /create/video:
    post:
      operationId: createVideo
      summary: A short video from a prompt, with camera moves and models
      description: A short video (4-10 s) from your own prompt, optionally starting from or guided by up to 3 reference photos, with a camera move (dolly_zoom, crane, orbit, push_in, whip_pan, low_angle) and sound. Our engine costs 2 credits per video; premium models cost more (see get_create_options). Poll list_creations.
      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:
                prompt:
                  type: string
                  description: 'The shot: subject, action, place, light, mood'
                aspect:
                  type: string
                  enum:
                  - '9:16'
                  - '4:5'
                  - '1:1'
                  - '16:9'
                  default: '9:16'
                  description: 'Frame: 9:16 vertical (TikTok, Reels, Shorts), 4:5, 1:1, 16:9 (YouTube, covers, banners)'
                seconds:
                  type: integer
                  enum:
                  - 4
                  - 6
                  - 8
                  - 10
                  default: 8
                model:
                  type: string
                  default: standard
                  description: Video model id from get_create_options; standard = our engine
                camera:
                  type: string
                  enum:
                  - dolly_zoom
                  - crane
                  - orbit
                  - push_in
                  - whip_pan
                  - low_angle
                  description: Optional camera move
                sound:
                  type: boolean
                  default: true
                reference_images:
                  type: array
                  items:
                    type: string
                  maxItems: 3
                  description: 'Reference photos (the first one can be the start frame): CartViral /u/ links or public https file links, up to 3'
              required:
              - prompt
      tags:
      - Create
  /create/angles:
    post:
      operationId: makeAngles
      summary: New angles of one photo
      description: 'New angles of the same shoot from one photo (three-quarter, side, top, macro, low, front, wide, detail): 4 angles 4 credits, 6 angles 6 credits, 8 angles 8 credits. Poll list_creations.'
      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:
                image:
                  type: string
                  description: 'The photo: a CartViral /u/ link, or any public https link to the file (downloaded once)'
                count:
                  type: integer
                  enum:
                  - 4
                  - 6
                  - 8
                  default: 6
                aspect:
                  type: string
                  enum:
                  - '9:16'
                  - '4:5'
                  - '1:1'
                  - '16:9'
                  default: '9:16'
                  description: 'Frame: 9:16 vertical (TikTok, Reels, Shorts), 4:5, 1:1, 16:9 (YouTube, covers, banners)'
              required:
              - image
      tags:
      - Create
  /create/talking-photo:
    post:
      operationId: makeTalkingPhoto
      summary: A photo says your text on camera
      description: A person's photo says your text on camera, in any language (up to 700 characters). 2 credits per take of up to 10 s (about 26 words); model avatar (Kling Avatar, when available) costs more. Needs consent=true for a real person. Poll list_creations.
      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:
                image:
                  type: string
                  description: 'The person''s photo, face clearly visible: a CartViral /u/ link, or any public https link to the file (downloaded once)'
                text:
                  type: string
                  description: What the person says
                consent:
                  type: boolean
                  description: true = it is the user on the photo, or the user has that person's consent. Required for a real person's photo.
                model:
                  type: string
                  enum:
                  - standard
                  - avatar
                  default: standard
                voice:
                  type: string
                  enum:
                  - female
                  - male
                  description: Voice for the avatar model
                aspect:
                  type: string
                  enum:
                  - '9:16'
                  - '4:5'
                  - '1:1'
                  - '16:9'
                  default: '9:16'
                  description: 'Frame: 9:16 vertical (TikTok, Reels, Shorts), 4:5, 1:1, 16:9 (YouTube, covers, banners)'
              required:
              - image
              - text
              - consent
      tags:
      - Create
  /create/cinematic:
    post:
      operationId: makeCinematic
      summary: A 15 or 30 s brand film of a product
      description: 'A 15 or 30 s image film of a product with a pro model, every frame usable as a banner: for a site, ads and banners. Pass a catalog product_id or up to 3 product photos. 12 credits for 15 s and 18 for 30 s on our engine; premium models cost more (get_create_options). Poll list_creations.'
      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: false
        content:
          application/json:
            schema:
              type: object
              properties:
                product_id:
                  type: string
                  description: Product id from list_products (or pass images)
                images:
                  type: array
                  items:
                    type: string
                  maxItems: 3
                  description: 'Product photos when there is no product_id: CartViral /u/ links or public https file links, up to 3'
                title:
                  type: string
                  description: Product name, when there is no product_id
                mood:
                  type: string
                  enum:
                  - luxury
                  - fresh
                  - bold
                  - soft
                  default: luxury
                seconds:
                  type: integer
                  enum:
                  - 15
                  - 30
                  default: 15
                model:
                  type: string
                  default: standard
                aspect:
                  type: string
                  enum:
                  - '9:16'
                  - '4:5'
                  - '1:1'
                  - '16:9'
                  default: '9:16'
                  description: 'Frame: 9:16 vertical (TikTok, Reels, Shorts), 4:5, 1:1, 16:9 (YouTube, covers, banners)'
                with_person:
                  type: boolean
                  default: true
                  description: A model on screen with the product
                tagline:
                  type: string
                  description: Optional end line, up to 60 characters
                language:
                  type: string
                  enum:
                  - en
                  - ru
                  default: en
              required: []
      tags:
      - Create
  /create/reframe:
    post:
      operationId: reframeVideo
      summary: Change a video's frame (9:16, 4:5, 1:1, 16:9)
      description: 'Re-cut a video (up to 2 minutes) to another frame: 9:16, 4:5, 1:1 or 16:9, filling the frame or on a blurred background. 1 credit. Poll list_creations.'
      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:
                video:
                  type: string
                  description: 'The video: a CartViral /u/ link, or any public https link to the file (downloaded once)'
                aspect:
                  type: string
                  enum:
                  - '9:16'
                  - '4:5'
                  - '1:1'
                  - '16:9'
                  default: '9:16'
                  description: 'Frame: 9:16 vertical (TikTok, Reels, Shorts), 4:5, 1:1, 16:9 (YouTube, covers, banners)'
                fit:
                  type: string
                  enum:
                  - fill
                  - blur
                  default: fill
              required:
              - video
              - aspect
      tags:
      - Create
  /create/remove-background:
    post:
      operationId: removeBackground
      summary: Cut-out PNG and white-background JPG
      description: A cut-out PNG with a transparent background plus a white-background JPG. 1 credit. Poll list_creations.
      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:
                image:
                  type: string
                  description: 'The photo: a CartViral /u/ link, or any public https link to the file (downloaded once)'
              required:
              - image
      tags:
      - Create
  /create/motion:
    post:
      operationId: copyMotion
      summary: A character repeats a reference video's movement
      description: The person from a photo repeats the movement of a reference video (dance, gesture, walk), up to 15 s. Premium, priced by length; only when premium video is switched on. Needs consent=true for a real person. Poll list_creations.
      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:
                video:
                  type: string
                  description: 'The video with the movement: a CartViral /u/ link, or any public https link to the file (downloaded once)'
                image:
                  type: string
                  description: 'The character''s photo: a CartViral /u/ link, or any public https link to the file (downloaded once)'
                prompt:
                  type: string
                  description: 'Optional: the scene or style'
                consent:
                  type: boolean
                  description: true = it is the user on the photo, or the user has that person's consent. Required for a real person's photo.
              required:
              - video
              - image
              - consent
      tags:
      - Create
  /create/breakdown:
    post:
      operationId: breakdownVideo
      summary: 'Why a viral video works: hook, beats, timings (free)'
      description: 'Why a video works: hook and its mechanism, beats with timings, what is said and shown, on-screen text style, measured cuts. Free. To make the same structure with your product or without one, use remake_from_reference. Poll list_creations (the result is data).'
      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:
                video:
                  type: string
                  description: 'The video file (a direct link, not a social post page): a CartViral /u/ link, or any public https link to the file (downloaded once)'
                language:
                  type: string
                  default: en
                  description: Language of the breakdown, e.g. en, ru, es
              required:
              - video
      tags:
      - Create
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