> ## Documentation Index
> Fetch the complete documentation index at: https://docs.video2ctx.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate an AI video plan from trend signals

> Uses Kimi K2.6 for strategic synthesis and automatically falls back to GPT-OSS 120B when Kimi is unavailable. The response identifies the model that produced it.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/trends/plan
openapi: 3.1.0
info:
  title: video2ctx API
  version: 1.0.0
  license:
    name: Apache License 2.0
    identifier: Apache-2.0
  description: >-
    Consumer-facing contract for the hosted video2ctx API. First-party
    application and operator routes are documented separately at
    https://docs.video2ctx.dev/internals/overview.
servers:
  - url: https://api.video2ctx.dev
    description: Hosted video2ctx API
security: []
tags:
  - name: System
    description: Service status and machine-readable documentation.
  - name: Providers
    description: Supported external video providers and their capabilities.
  - name: Discovery
    description: Search, browse, and trend research.
  - name: Videos
    description: Video metadata and evidence.
  - name: Channels
    description: Channel inspection.
  - name: Playlists
    description: Playlist inspection.
  - name: Projects
    description: Private research projects and saved material.
  - name: Research
    description: Imports, jobs, cited answers, comparisons, and reports.
  - name: Exports
    description: Project export creation and download.
  - name: Monitoring
    description: Monitors, notifications, and digest preferences.
  - name: Billing
    description: Checkout, usage, and Stripe webhook handling.
paths:
  /v1/trends/plan:
    post:
      tags:
        - Discovery
      summary: Generate an AI video plan from trend signals
      description: >-
        Uses Kimi K2.6 for strategic synthesis and automatically falls back to
        GPT-OSS 120B when Kimi is unavailable. The response identifies the model
        that produced it.
      operationId: generateTrendPlan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - report
              properties:
                report:
                  $ref: '#/components/schemas/TrendReport'
      responses:
        '200':
          description: Evidence-grounded video plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiTrendPlan'
          headers:
            X-Credits-Charged:
              $ref: '#/components/headers/CreditsCharged'
            X-Credits-Remaining:
              $ref: '#/components/headers/CreditsRemaining'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - bearerApiKey: []
        - sessionCookie: []
        - apiKey: []
        - demoUser: []
components:
  schemas:
    TrendReport:
      type: object
      required:
        - provider
        - query
        - generatedAt
        - sampleSize
        - methodologyVersion
        - methodology
        - sample
        - confidence
        - summary
        - videos
        - hashtags
        - titlePatterns
        - durationMix
        - plan
        - warnings
      properties:
        provider:
          type: string
          enum:
            - youtube
        query:
          type: string
        generatedAt:
          type: string
          format: date-time
        sampleSize:
          type: integer
          minimum: 0
        methodologyVersion:
          const: '2.0'
        methodology:
          type: string
        sample:
          type: object
          required:
            - candidateVideos
            - enrichedVideos
            - channels
            - observedVideos
          properties:
            candidateVideos:
              type: integer
              minimum: 0
            enrichedVideos:
              type: integer
              minimum: 0
            channels:
              type: integer
              minimum: 0
            observedVideos:
              type: integer
              minimum: 0
        confidence:
          type: object
          required:
            - score
            - level
            - reasons
          properties:
            score:
              type: integer
              minimum: 0
              maximum: 100
            level:
              type: string
              enum:
                - low
                - medium
                - high
            reasons:
              type: array
              items:
                type: string
        summary:
          type: object
          required:
            - totalViews
            - medianViewsPerHour
            - publishedLast7Days
            - breakoutCount
            - acceleratingCount
          properties:
            totalViews:
              type: integer
              minimum: 0
            medianViewsPerHour:
              type: number
              minimum: 0
            publishedLast7Days:
              type: integer
              minimum: 0
            breakoutCount:
              type: integer
              minimum: 0
            acceleratingCount:
              type: integer
              minimum: 0
            medianObservedViewsPerHour:
              type: number
              minimum: 0
        videos:
          type: array
          items:
            $ref: '#/components/schemas/TrendVideo'
        hashtags:
          type: array
          items:
            type: object
            additionalProperties: true
        titlePatterns:
          type: array
          items:
            type: object
            additionalProperties: true
        durationMix:
          type: array
          items:
            type: object
            additionalProperties: true
        insights:
          type: object
          description: >-
            Optional GLM-generated analysis. Omitted when deterministic mode is
            requested or model inference fails.
          additionalProperties: true
        plan:
          type: object
          additionalProperties: true
        warnings:
          type: array
          items:
            type: string
    AiTrendPlan:
      type: object
      required:
        - provider
        - model
        - generatedAt
        - angle
        - audience
        - hook
        - recommendedDurationSeconds
        - outline
        - titleIdeas
        - hashtags
        - differentiation
        - evidence
        - caveats
        - operationId
      properties:
        provider:
          $ref: '#/components/schemas/ProviderId'
        model:
          type: string
          enum:
            - '@cf/moonshotai/kimi-k2.6'
            - '@cf/openai/gpt-oss-120b'
        generatedAt:
          type: string
          format: date-time
        angle:
          type: string
        audience:
          type: string
        hook:
          type: string
        recommendedDurationSeconds:
          type: integer
        outline:
          type: array
          items:
            type: object
            required:
              - section
              - goal
            properties:
              section:
                type: string
              goal:
                type: string
        titleIdeas:
          type: array
          items:
            type: string
        hashtags:
          type: array
          items:
            type: string
        differentiation:
          type: array
          items:
            type: string
        evidence:
          type: array
          items:
            type: object
            required:
              - claim
              - videoIds
            properties:
              claim:
                type: string
              videoIds:
                type: array
                items:
                  type: string
        caveats:
          type: array
          items:
            type: string
        operationId:
          type: string
          format: uuid
    TrendVideo:
      type: object
      required:
        - id
        - title
        - channel
        - thumbnails
        - description
        - viewCount
        - signalSource
        - confidenceScore
        - hashtags
        - keywords
        - trendScore
        - trendBand
        - url
      properties:
        id:
          type: string
        title:
          type: string
        channel:
          type: object
          required:
            - id
            - name
          properties:
            id:
              type: string
            name:
              type: string
        thumbnails:
          type: array
          items:
            $ref: '#/components/schemas/Thumbnail'
        description:
          type: string
        durationSeconds:
          type: integer
          minimum: 0
        publishedTimeText:
          type: string
        publishDate:
          type: string
        ageHours:
          type: number
          minimum: 0
        viewCount:
          type: integer
          minimum: 0
        viewsPerHour:
          type: number
          minimum: 0
        observedViewsPerHour:
          type: number
          minimum: 0
        previousViewsPerHour:
          type: number
          minimum: 0
        accelerationPercent:
          type: number
        observationHours:
          type: number
          minimum: 0
        viewDelta:
          type: integer
          minimum: 0
        likeDelta:
          type: integer
          minimum: 0
        commentDelta:
          type: integer
          minimum: 0
        commentCount:
          type: integer
          minimum: 0
        likeCount:
          type: integer
          minimum: 0
        engagementRate:
          type: number
          minimum: 0
        channelBaselineViewsPerHour:
          type: number
          minimum: 0
        channelLift:
          type: number
          minimum: 0
        searchRank:
          type: integer
          minimum: 1
        signalSource:
          type: string
          enum:
            - observed
            - estimated
        confidenceScore:
          type: integer
          minimum: 0
          maximum: 100
        hashtags:
          type: array
          items:
            type: string
        keywords:
          type: array
          items:
            type: string
        trendScore:
          type: integer
          minimum: 0
          maximum: 100
        trendBand:
          type: string
          enum:
            - Breakout
            - Rising
            - Steady
        url:
          type: string
          format: uri
    ProviderId:
      type: string
      enum:
        - youtube
      example: youtube
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              example: QUERY_REQUIRED
            message:
              type: string
            details: {}
            requestId:
              type: string
    Thumbnail:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
        width:
          type: integer
          minimum: 0
        height:
          type: integer
          minimum: 0
  headers:
    CreditsCharged:
      description: Credits settled for this operation.
      schema:
        type: integer
        minimum: 0
    CreditsRemaining:
      description: Current balance in the owning user account after the request is metered.
      schema:
        type: integer
  responses:
    Unauthorized:
      description: Authentication is required.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InsufficientCredits:
      description: >-
        The user account does not have enough credits. Error code:
        INSUFFICIENT_CREDITS.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        X-Credits-Charged:
          $ref: '#/components/headers/CreditsCharged'
        X-Credits-Remaining:
          $ref: '#/components/headers/CreditsRemaining'
    Forbidden:
      description: The caller is not allowed to perform this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: The request failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: The public rate limit was exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: An unexpected server error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: An upstream AI or YouTube service is unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerApiKey:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: >-
        Permanent personal API key created in the dashboard. Example: curl -H
        "Authorization: Bearer aty_…" https://your-host/v1/projects
    sessionCookie:
      type: apiKey
      in: cookie
      name: better-auth.session_token
      description: >-
        Better Auth session cookie. A production deployment may use the
        secure-prefixed cookie name; same-origin browser requests send it
        automatically.
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Legacy-compatible header for a permanent personal API key. Prefer
        Authorization: Bearer aty_….
    demoUser:
      type: apiKey
      in: header
      name: X-Demo-User
      description: >-
        Local development only. Any stable value selects an isolated demo
        account. Rejected in production.

````