Shuffle Video Chain API

openapi: 3.2.0
info:
  title: FarCash Longform Video Video Chain API
  version: 1.0.0
  description: API for AI-powered long-form video generation. Supports automated and manual clip-by-clip workflows, credit management, and L402 payments.
servers:
- url: https://www.textshuffle.com
  description: Current environment
security:
- BearerAuth: []
tags:
- name: Video Chain
paths:
  /api/longform-video/generate:
    post:
      tags:
      - Video Chain
      operationId: createVideoChain
      summary: Create a new video generation chain
      description: Creates either an automated or manual video generation chain. Automated mode generates all clips sequentially from a single prompt. Manual mode creates one clip at a time with user control.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - prompt
              properties:
                prompt:
                  type: string
                  minLength: 10
                  maxLength: 30000
                  description: Scene description for video generation
                imageUrl:
                  type: string
                  format: uri
                  description: Input image URL for image-to-video generation
                durationSeconds:
                  type: integer
                  minimum: 4
                  maximum: 300
                  description: Total video duration (automated mode only)
                mode:
                  type: string
                  enum:
                  - manual
                  - automated
                  default: automated
                  description: 'automated: full video from prompt. manual: build clip by clip'
                tier:
                  type: string
                  enum:
                  - fast
                  - standard
                  default: standard
                generation:
                  type: string
                  enum:
                  - '3.0'
                  - '3.1'
                  default: '3.1'
                  description: Veo model version
                stability:
                  type: string
                  enum:
                  - preview
                  - stable
                  default: stable
                clipDurationSeconds:
                  type: integer
                  enum:
                  - 4
                  - 6
                  - 8
                  default: 8
                  description: Duration of each clip in seconds
                resolution:
                  type: string
                  enum:
                  - 720p
                  - 1080p
                  - 4k
                  default: 720p
                aspectRatio:
                  type: string
                  enum:
                  - '16:9'
                  - '9:16'
                  default: '16:9'
                generateAudio:
                  type: boolean
                  default: true
                  description: Generate audio with video
                negativePrompt:
                  type: string
                  description: Things to avoid in generation
                seed:
                  type: integer
                  description: Reproducibility seed
                compressionQuality:
                  type: string
                  enum:
                  - lossless
                  - optimized
                  default: optimized
                personGeneration:
                  type: string
                  enum:
                  - dont_allow
                  - allow_adult
                  default: allow_adult
                sampleCount:
                  type: integer
                  minimum: 1
                  maximum: 4
                  default: 1
                resizeMode:
                  type: string
                  enum:
                  - pad
                  - crop
                  description: Only applicable with imageUrl
      responses:
        '200':
          description: Chain created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  chainId:
                    type: string
                  status:
                    type: string
                    enum:
                    - created
                  mode:
                    type: string
                    enum:
                    - manual
                    - automated
                  message:
                    type: string
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Insufficient credits (includes L402 offers)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  version:
                    type: string
                  payment_request_url:
                    type: string
                  offers:
                    type: array
                    items:
                      $ref: '#/components/schemas/L402Offer'
  /api/longform-video/status/{chainId}:
    get:
      tags:
      - Video Chain
      operationId: getVideoChainStatus
      summary: Get video chain status
      description: Returns the current status, progress, and step details of a video chain. No authentication required — the chain ID acts as an unguessable access token.
      security: []
      parameters:
      - name: chainId
        in: path
        required: true
        schema:
          type: string
        description: Video chain ID returned from /generate
      responses:
        '200':
          description: Chain status
          content:
            application/json:
              schema:
                type: object
                properties:
                  chainId:
                    type: string
                  status:
                    type: string
                    enum:
                    - ACTIVE
                    - COMPLETED
                    - FAILED
                    - CANCELLED
                    - AWAITING_RETRY
                  mode:
                    type: string
                    enum:
                    - MANUAL
                    - AUTOMATED
                  stitchStatus:
                    type:
                    - string
                    - 'null'
                  chainSettings:
                    $ref: '#/components/schemas/ChainSettings'
                  progress:
                    $ref: '#/components/schemas/Progress'
                  isComplete:
                    type: boolean
                  videoUrl:
                    type:
                    - string
                    - 'null'
                  error:
                    type:
                    - string
                    - 'null'
                  steps:
                    type: array
                    items: {}
        '404':
          description: Chain not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/longform-video/cancel-chain:
    post:
      tags:
      - Video Chain
      operationId: cancelVideoChain
      summary: Cancel an active video chain
      description: Cancels an in-progress video chain. If a clip is currently generating, cancellation is deferred until it finishes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - chainId
              properties:
                chainId:
                  type: string
      responses:
        '200':
          description: Chain cancelled
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  deferred:
                    type: boolean
                    description: true if cancel will execute after current clip finishes
        '403':
          description: Not the owner of this chain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Chain cannot be cancelled in current state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/longform-video/retry-step:
    post:
      tags:
      - Video Chain
      operationId: retryStep
      summary: Retry a failed generation step
      description: Retries a failed step with a new prompt. The chain must be in AWAITING_RETRY status.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - chainId
              - stepId
              - newPrompt
              properties:
                chainId:
                  type: string
                stepId:
                  type: string
                newPrompt:
                  type: string
      responses:
        '200':
          description: Step retry initiated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  newStepId:
                    type: string
components:
  schemas:
    Progress:
      type: object
      properties:
        currentStep:
          type: integer
        totalSteps:
          type: integer
        completedSteps:
          type: integer
        failedSteps:
          type: integer
        percentComplete:
          type: integer
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      required:
      - error
    ChainSettings:
      type: object
      properties:
        model:
          type: string
        resolution:
          type: string
          enum:
          - 720p
          - 1080p
          - 4k
        aspectRatio:
          type: string
          enum:
          - '16:9'
          - '9:16'
        generateAudio:
          type: boolean
        clipDurationSeconds:
          type: integer
        creditCostPerClip:
          type: integer
    L402Offer:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
        amount:
          type: integer
          description: Price in cents (USD)
        currency:
          type: string
        type:
          type: string
          enum:
          - top-up
        balance:
          type: integer
          description: Credits awarded on purchase
        payment_methods:
          type: array
          items:
            type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Use either a Privy ID token or an API key (format: fv_<32 hex chars>)'