GEN Generations API

openapi: 3.2.0
info:
  title: Auto Content Engine Generations API
  description: 'The GEN Auto Content Engine API takes a raw idea all the way to a published video — agent setup, idea research, vidsheet production, layer composition, render, and publish.


    ## The 5-step journey


    Every operation belongs to one phase of a 5-step user journey. Each operation carries an `x-phase` extension you can filter on:


    | Phase | Meaning |

    |-------|---------|

    | `setup` | Step 1 — Set Up Your Agent (identity, voice, personality, API keys, workspaces) |

    | `ideas` | Step 2 — Generate Content Ideas (trending data, research, refinement, preferences) |

    | `convert` | Step 3 — Convert Idea to Vidsheet (clone template or build custom engine) |

    | `edit` | Step 4 — Edit & Generate (cells, layers, creation cards, trigger + poll) |

    | `export` | Step 5 — Export & Publish (render, download, publish to social) |


    Full journey-oriented docs: https://api.gen.pro


    ## Authentication


    All endpoints require authentication via one of:


    - **API Key** (recommended): Pass your API key in the `X-API-Key` header. Create keys on the agent''s API page in the GEN dashboard.

    - **JWT**: Pass a Bearer JWT in the `Authorization: Bearer ` header.


    ## Base URLs


    ```

    https://api.gen.pro/v1 — agent setup, vidsheets, generations, renders, publishing

    https://agent.gen.pro/v1 — content ideas, research, conversations, chat

    https://agent-core.gen.pro/v1 — agent core (brand profile, watchlists, scheduled tasks)

    https://python.gen.pro — social publishing integration (connect, schedule, remove posts)

    ```


    Each operation carries its own `servers` entry, so a generated client or a

    hand-written call goes to the backend that serves the route.


    ## Credits


    All `/v1/vidsheet/` endpoints require an active GEN credit balance.

    If your organization has no usable credits, requests return `422` with error code `usable_gen_credit_required`.


    Credits can be funded with x402 by calling `POST /v1/x402_credit_purchase`

    with `workspace_id` plus `amount_usd` or `credits`. If `network` is omitted,

    GEN returns every configured payment option in `payment_methods` and

    `payment_required.accepts`; show the Sui, Solana, and Base options to the

    user or calling agent and sign one selected accept entry. Workspace funding

    wallets are backend settlement infrastructure; the user-facing payment

    choices are the returned payment methods.'
  version: 1.0.0
  contact:
    name: GEN Support
    url: https://gen.pro
  license:
    name: Proprietary
servers:
- url: https://api.gen.pro/v1
  description: Auto Content Engine API
- url: https://agent.gen.pro/v1
  description: Agent Chat API
- url: https://agent-core.gen.pro/v1
  description: Agent Core API (watchlists)
- url: https://python.gen.pro
  description: Publishing integration API (social connect and scheduling)
security:
- apiKey: []
- bearerAuth: []
tags:
- name: Generations
  description: Trigger AI content generation on cells and layers.
paths:
  /vidsheet/{sheet_id}/cells/{cell_id}/generate:
    post:
      operationId: generateCellContent
      x-mcp-tool: gen_vidsheet_action
      x-mcp-branch: generate (cell)
      x-phase: edit
      summary: Generate content for a cell
      description: 'Triggers AI content generation for a cell. Credits are pre-charged.

        Poll the generation status via `GET /v1/generations/{id}`.'
      tags:
      - Generations
      parameters:
      - $ref: '#/components/parameters/AgentId'
      - $ref: '#/components/parameters/SheetId'
      - $ref: '#/components/parameters/CellId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - generation_type
              - data
              properties:
                generation_type:
                  type: string
                  description: 'The type of AI generation to run. Canonical names:

                    text, image_from_text, video_from_text, video_from_image,

                    video_from_ingredients, speech_from_text, lipsync, captions,

                    transcription, song.

                    Use canonical names for new integrations. Uploaded media is a

                    cell value (PATCH the cell), not a generation.

                    '
                  enum:
                  - text
                  - image_from_text
                  - video_from_text
                  - video_from_image
                  - video_from_ingredients
                  - speech_from_text
                  - lipsync
                  - captions
                  - transcription
                  - song
                  example: text
                data:
                  type: object
                  description: 'Generation parameters (varies by type). Video generation card data may include

                    `aspect_ratio`, `duration`, optional `resolution` (`1080p` or `720p` where

                    supported), and optional `native_audio` for models that support native audio.

                    Omitted optional fields use the cell defaults or the closest supported model defaults.


                    Video generation accepts the Veo, Kling, Seedance and Grok models plus

                    `gemini-omni-flash-preview` (Gemini Omni Flash, 1-10s). Image generation with

                    `model: "gemini"` takes `version`: `nano-banana`, `nano-banana-pro`,

                    `nano-banana-2` or `nano-banana-2-lite`. The full per-card model lists are on

                    the card reference pages.


                    Song data (`generation_type: "song"`) takes `prompt`, `model` (`suno-v5-beta`,

                    `suno-v4.5plus-beta` or `suno-v5.5-beta`), `duration`, `instrumental`, `style`,

                    `title`, `negative_tags` and `vocal_gender`, plus optional source audio:

                    `source_audio_resource_id` (an existing audio content resource) or a public

                    HTTPS URL as `source_audio_url` (imported as a content resource first), and

                    `audio_weight` (0.0-1.0) for fidelity to the source. Source audio is capped at

                    8 minutes (480 s); longer input is refused before any charge.

                    '
                  example:
                    prompt: A handheld product demo video
                    model: veo-3.1
                    aspect_ratio: '9:16'
                    resolution: 1080p
                    duration: 8
                    native_audio: false
      responses:
        '201':
          description: Generation started
          content:
            application/json:
              schema:
                type: object
                properties:
                  generation_id:
                    type: string
                  status:
                    type: string
                    example: pending
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Insufficient credits or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /vidsheet/{sheet_id}/cells/{cell_id}/layers/{layer_id}/generate:
    post:
      operationId: generateLayerContent
      x-mcp-tool: gen_vidsheet_action
      x-mcp-branch: generate (layer)
      x-phase: edit
      summary: Generate content for a layer
      description: 'Triggers AI generation for a video layer (voice, music, clip, etc.).

        Credits are pre-charged. Poll status via `GET /v1/generations/{id}`.'
      tags:
      - Generations
      parameters:
      - $ref: '#/components/parameters/AgentId'
      - $ref: '#/components/parameters/SheetId'
      - $ref: '#/components/parameters/CellId'
      - $ref: '#/components/parameters/LayerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - generation_type
              - data
              properties:
                generation_type:
                  type: string
                  description: Generation type — see cell generate endpoint for full list.
                  example: speech_from_text
                data:
                  type: object
      responses:
        '201':
          description: Generation started
          content:
            application/json:
              schema:
                type: object
                properties:
                  generation_id:
                    type: string
                  status:
                    type: string
                    example: pending
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '422':
          $ref: '#/components/responses/ApiValidationError'
  /generations/{generation_id}:
    get:
      operationId: getGeneration
      x-mcp-tool: gen_discover
      x-mcp-branch: vidsheet.generation
      x-phase: edit
      summary: Get generation status
      description: Check the status and result of an AI generation job.
      tags:
      - Generations
      parameters:
      - name: generation_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Generation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Generation'
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '422':
          $ref: '#/components/responses/ApiValidationError'
  /generations/{generation_id}/stop:
    post:
      operationId: stopGeneration
      x-mcp-tool: gen_vidsheet_action
      x-mcp-branch: <flat ops>
      x-phase: edit
      summary: Stop a generation
      description: Cancels a running generation. Credits are refunded.
      tags:
      - Generations
      parameters:
      - name: generation_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: JSON request body.
              properties:
                agent_id:
                  type: string
                  description: Agent context; the controller reads params[:agent_id] (`require_agent!`).
              required:
              - agent_id
      responses:
        '200':
          description: Generation stopped
          content:
            application/json:
              schema:
                type: object
                properties:
                  generation_id:
                    type: string
                  status:
                    type: string
                    example: stopped
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '422':
          $ref: '#/components/responses/ApiValidationError'
  /generations/{generation_id}/continue:
    post:
      operationId: continueGeneration
      x-mcp-tool: gen_vidsheet_action
      x-mcp-branch: <flat ops>
      x-phase: edit
      summary: Continue a stopped generation
      description: Resumes a previously stopped generation. Credits are re-charged.
      tags:
      - Generations
      parameters:
      - name: generation_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: JSON request body. Every field other than the routing keys is forwarded verbatim to `UserJobs::Continue`.
              additionalProperties: true
              properties:
                agent_id:
                  type: string
                  description: Agent context; the controller reads params[:agent_id] (`require_agent!`).
              required:
              - agent_id
      responses:
        '200':
          description: Generation resumed
          content:
            application/json:
              schema:
                type: object
                properties:
                  generation_id:
                    type: string
                  status:
                    type: string
                    example: pending
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '422':
          $ref: '#/components/responses/ApiValidationError'
  /transcriptions:
    post:
      operationId: createTranscription
      x-mcp-tool: gen_generate
      x-mcp-branch: transcribe
      x-phase: edit
      summary: Transcribe audio or video
      description: 'Transcribes audio or video to text without a sheet or cell. Pass exactly one

        source in `data`: `audio`, `video`, or `content_resource_id`. Returns a

        generation id — poll `GET /v1/generations/{id}` until status is "completed",

        then read `result`. Uses credits based on the duration of audio transcribed;

        credits are pre-charged and refunded on failure.


        Use the `captions` generation type instead when you need word-level timings

        for subtitle overlays on a video.'
      tags:
      - Generations
      parameters:
      - $ref: '#/components/parameters/AgentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  $ref: '#/components/schemas/TranscriptionData'
      responses:
        '201':
          description: Transcription job created
          content:
            application/json:
              schema:
                type: object
                properties:
                  generation_id:
                    type: integer
                  status:
                    type: string
                    example: pending
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: 'Invalid source (`validation_error`) or not enough workspace credits

            (`insufficient_credits_for_job`).

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /vidsheet/{sheet_id}/cells/{cell_id}/render:
    post:
      operationId: renderVideo
      x-mcp-tool: gen_vidsheet_action
      x-mcp-branch: generate (cell, creation_card_type=final-video)
      x-phase: export
      summary: Render final video
      description: 'Composites all layers (video, audio, captions, text overlays) into a final video.

        The result appears in the final_video column cell.

        Returns a generation_id — poll `GET /v1/generations/{id}` until status is "completed".

        Credits are pre-charged and refunded on failure.'
      tags:
      - Generations
      parameters:
      - $ref: '#/components/parameters/AgentId'
      - $ref: '#/components/parameters/SheetId'
      - $ref: '#/components/parameters/CellId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: JSON request body.
              properties:
                generation_type:
                  type: string
                  description: Canonical generation type for the render; resolved through `VidsheetSchema::CanonicalGenerationType`.
                data:
                  type: object
                  additionalProperties: true
                  description: Card inputs; accepted as an object or a JSON-encoded string.
      responses:
        '201':
          description: Render started
          content:
            application/json:
              schema:
                type: object
                properties:
                  generation_id:
                    type: string
                  status:
                    type: string
                    example: pending
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /user_jobs:
    get:
      operationId: getUserJobs
      x-phase: setup
      summary: Schedule, publish, or remove posts — publish content
      tags:
      - Generations
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: A UserJob (`app/resources/user_job_resource.rb`).
                  properties:
                    id: {}
                    status: {}
                    user_job_type: {}
                    failed_reason: {}
                    user_message: {}
                    container_id: {}
                    container_type: {}
                    result: {}
                    object_type:
                      description: Always the literal "UserJob".
                      const: UserJob
                    seed: {}
                    raw_data: {}
                    input_nodes:
                      type: array
                      items: {}
                    output_nodes:
                      type: array
                      items: {}
                    output_resources:
                      type: array
                      items: {}
                    child_jobs:
                      type: array
                      items: {}
                    credit_outcome:
                      enum:
                      - refunded
                      - charged
                      - not_charged
                    retryable:
                      type: boolean
                    stage: {}
                    processing_started_at: {}
                    execution_cost:
                      description: Stringified credit cost.
                      type: string
                description: '`head :ok`-style list; `UserJobResource` per job.'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ApiValidationError'
      x-mcp-tool: gen_publish_action
      x-mcp-branch: publish_content
  /user_jobs/estimate:
    post:
      operationId: postUserJobsEstimate
      x-phase: setup
      summary: Create, update, or remove assistants and their profiles — create look
      tags:
      - Generations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: One job (`user_job`) or a batch (`user_jobs`).
              required:
              - user_job
              properties:
                agent_id:
                  type: string
                  description: Agent context; the controller reads params[:agent_id] (`require_agent!`).
                user_job:
                  description: 'One job descriptor: `{user_job_type, data}`.'
                user_jobs:
                  description: 'Batch form: array of the same descriptor (max `MAX_ESTIMATE_USER_JOBS`).'
                  type: array
                  items: {}
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  estimate_id: {}
                  estimate_request_key: {}
                  estimated_credits: {}
                  status: {}
                  items:
                    type: array
                    items: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ApiValidationError'
      x-mcp-tool: gen_agent_action
      x-mcp-branch: create_look
components:
  parameters:
    AgentId:
      name: agent_id
      in: query
      required: true
      description: The agent ID. Find via `GET /v1/agents`.
      schema:
        type: string
    LayerId:
      name: layer_id
      in: path
      required: true
      schema:
        type: string
    SheetId:
      name: sheet_id
      in: path
      required: true
      schema:
        type: string
    CellId:
      name: cell_id
      in: path
      required: true
      schema:
        type: string
  schemas:
    TranscriptionSource:
      type: object
      required:
      - value
      properties:
        value:
          type: string
          format: uri
          description: Publicly reachable URL of the media to transcribe.
          example: https://cdn.example.com/episode-12.mp3
        key:
          type: string
          description: Optional storage key for the media.
    ApiError:
      type: object
      required:
      - code
      properties:
        code:
          type: string
          description: The stable machine-readable failure code.
        message:
          type: string
          description: Human-readable failure detail.
        errors:
          type: array
          description: Field-level validation failures.
          items:
            type: object
        retryable:
          type: boolean
          description: Whether retrying can succeed without changing the request.
        new_change_set_required:
          type: boolean
          description: Whether the caller must begin a new edit group.
        funding_error_kind:
          type: string
          description: The credit or payment failure category.
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable error message.
        error_code:
          type: string
          description: Machine-readable error code.
    TranscriptionTrim:
      type: object
      required:
      - start_seconds
      - duration_seconds
      description: Transcribe only part of the source.
      properties:
        start_seconds:
          type: number
          minimum: 0
          description: Offset to start transcribing from.
          example: 15
        duration_seconds:
          type: number
          exclusiveMinimum: 0
          description: How many seconds to transcribe.
          example: 30
    Generation:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
          - failed
          - stopped
        user_job_type:
          type: string
        result:
          type: object
          nullable: true
        failed_reason:
          type: string
          nullable: true
        output_resources:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              url:
                type: string
                format: uri
              thumbnail_url:
                type: string
                format: uri
                nullable: true
              object_type:
                type: string
                description: '"Video", "Image", etc.'
              type:
                type: string
        execution_cost:
          type: string
          nullable: true
    TranscriptionData:
      type: object
      description: 'The source to transcribe. Pass exactly one of `audio`, `video`, or

        `content_resource_id`. `audio` and `video` are mutually exclusive;

        `trim` may accompany either.

        '
      oneOf:
      - type: object
        required:
        - audio
        additionalProperties: false
        properties:
          audio:
            $ref: '#/components/schemas/TranscriptionSource'
          trim:
            $ref: '#/components/schemas/TranscriptionTrim'
      - type: object
        required:
        - video
        additionalProperties: false
        properties:
          video:
            $ref: '#/components/schemas/TranscriptionSource'
          trim:
            $ref: '#/components/schemas/TranscriptionTrim'
      - type: object
        required:
        - content_resource_id
        properties:
          content_resource_id:
            type: string
            description: ID of an audio or video content resource already uploaded to the agent.
            example: res_abc123
  responses:
    ApiUnauthorized:
      description: Missing or invalid authentication.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    ApiValidationError:
      description: Validation failed or the request could not be processed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unauthorized:
      description: Missing or invalid authentication.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized
            error_code: unauthorized
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Personal Access Token (PAT). Create one in Settings > API Keys.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer JWT issued by the GEN dashboard sign-in.