BAMF.ai Generate API

openapi: 3.2.0
info:
  title: BAMF Developer Platform Generate API
  version: 0.1.0
servers:
- url: https://api.bamf.ai/v1
security:
- BearerAuth: []
tags:
- name: Generate
paths:
  /generate/posts:
    post:
      summary: Create post generation job
      description: For LinkedIn, returns one concise candidate grounded in fetched creator context, plus one focused follow-up question when a material personal detail is missing. Private source context is not returned. Does not create a post. Pass platform=x for X-native concepts, hooks, threads, CTAs, and performance-informed copy.
      responses:
        '202':
          description: Post generation job queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiJobResponse'
      tags:
      - Generate
      operationId: postGeneratePosts
      x-operation-id-source: derived
  /generate/x-posts:
    post:
      summary: Create X post generation job
      description: Returns X-native single-post or thread concepts, draft copy, hook/CTA rationale, and platform-specific recommendations. Does not create a post.
      responses:
        '202':
          description: X post generation job queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiJobResponse'
      tags:
      - Generate
      operationId: postGenerateXPosts
      x-operation-id-source: derived
  /generate/post-edits:
    post:
      summary: Create post edit job
      description: Returns a reviewable edit proposal, quality audit, deterministic quality comparison, and PATCH payload. Does not patch the post. For rough or low-quality drafts, pass current_content/source_material with edit_mode=full_rewrite so BAMF can preserve keeper points and rebuild the post with creator context.
      responses:
        '202':
          description: Post edit job queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiJobResponse'
      tags:
      - Generate
      operationId: postGeneratePostEdits
      x-operation-id-source: derived
  /generate/images:
    post:
      summary: Create image generation job
      description: Generates quote cards, creator portrait images, infographics, and package-bound LinkedIn profile assets. reference_bindings preserves official identity, product, and brand truth separately from inspiration used only for style or layout. profile_banner is generated at 2400x800 then center-cropped/resized to 1584x396; profile_featured is generated at 1536x800 then center-cropped/resized to 1200x628. Profile jobs never attach to posts and return profile_package_asset.generated_asset with a durableRef when the job succeeds.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateImageRequest'
      responses:
        '202':
          description: Image generation job queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiJobResponse'
        '400':
          description: Invalid reference binding, profile package binding, asset slot, or post attachment
        '404':
          description: Active profile package not found for this creator
      tags:
      - Generate
      operationId: postGenerateImages
      x-operation-id-source: derived
  /generate/videos:
    post:
      summary: Create Higgsfield Seedance 2.5 video generation job
      description: Queues a paid video request. Supplying image_url or an official likeness reference uses Seedance 2.5 image-to-video to preserve the approved source identity; text-only requests use text-to-video. Successful jobs return a BAMF-hosted MP4 media asset and a provider request ID; failed, cancelled, or moderated requests are not reported as successful.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateVideoRequest'
      responses:
        '202':
          description: Video generation job queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiJobResponse'
        '400':
          description: Invalid video generation input
      tags:
      - Generate
      operationId: postGenerateVideos
      x-operation-id-source: derived
  /generate/music:
    post:
      summary: Generate an instrumental music track
      description: Requires images:generate. Generates a 10-30 second instrumental MP3 (default 15 seconds) from a prompt of up to 2000 characters, stores it in the creator media bucket, and returns its URL. Returns 503 music_provider_unavailable when the music provider is not configured.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - prompt
              properties:
                prompt:
                  type: string
                  maxLength: 2000
                duration_seconds:
                  type: integer
                  minimum: 10
                  maximum: 30
                  default: 15
                creator_id:
                  type: string
                  format: uuid
                author_id:
                  type: string
                  format: uuid
      responses:
        '201':
          description: 'Generated track: url, storage_path, duration_seconds, license'
        '400':
          description: invalid_prompt
        '503':
          description: Music provider unavailable
      tags:
      - Generate
      operationId: postGenerateMusic
      x-operation-id-source: derived
  /generate/talking-videos:
    post:
      summary: Create Higgsfield Speak v2 lip-synced talking video job
      description: Queues a paid lip-sync request that animates a creator image speaking the supplied script. The script must stay within 40 words (about 15 seconds of audio); BAMF picks the smallest 5, 10, or 15 second Speak v2 duration that fits. Product-launch founder shots select Higgsfield Speak explicitly; failures do not silently forward likeness or cloned-voice data to another video vendor. Successful jobs return a BAMF-hosted MP4 media asset; failed, cancelled, or moderated requests are not reported as successful.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateTalkingVideoRequest'
      responses:
        '202':
          description: Talking video generation job queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiJobResponse'
        '400':
          description: Invalid talking video input, including script_required or script_too_long
      tags:
      - Generate
      operationId: postGenerateTalkingVideos
      x-operation-id-source: derived
  /generate/carousels:
    post:
      summary: Create carousel generation job
      description: Generates slide images, packages them into a LinkedIn-ready PDF, and optionally attaches the PDF to a post.
      responses:
        '202':
          description: Carousel generation job queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiJobResponse'
      tags:
      - Generate
      operationId: postGenerateCarousels
      x-operation-id-source: derived
  /generate/carousel-pdfs:
    post:
      summary: Create carousel PDF job
      description: Converts existing slide image URLs into one PDF with one slide per page for LinkedIn carousel/document posts.
      responses:
        '202':
          description: Carousel PDF job queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiJobResponse'
      tags:
      - Generate
      operationId: postGenerateCarouselPdfs
      x-operation-id-source: derived
  /generate/brand-kits:
    post:
      summary: Create brand-kit generation job
      responses:
        '202':
          description: Brand-kit generation job queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiJobResponse'
      tags:
      - Generate
      operationId: postGenerateBrandKits
      x-operation-id-source: derived
components:
  schemas:
    ApiJob:
      type: object
      properties:
        id:
          type: string
        job_type:
          type: string
          enum:
          - post.generate
          - post.edit
          - image.generate
          - carousel.generate
          - carousel.pdf
          - brand_kit.generate
          - research.run
          - knowledge.process
          - analytics.sync
        status:
          type: string
          enum:
          - queued
          - running
          - succeeded
          - completed
          - failed
          - cancelled
          - canceled
        creator_id:
          type: string
        input:
          $ref: '#/components/schemas/JSONValue'
        output:
          $ref: '#/components/schemas/JSONValue'
        error:
          $ref: '#/components/schemas/JSONValue'
          description: Private founder-video jobs may return a PrivateVideoJobError with allowlisted stage, category, provider, request ID, status, and HTTP status fields; no raw provider text or URLs are exposed.
        created_at:
          type:
          - string
          - 'null'
          format: date-time
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
    GenerateTalkingVideoRequest:
      type: object
      required:
      - creator_id
      - script
      properties:
        engine:
          type: string
          enum:
          - auto
          - lipsync
          - veed_lipsync
          - fabric
          - omnihuman
          - kling
          - speak
          default: auto
          description: Talking-video engine. Product-launch founder shots use speak, which is Higgsfield-only and does not silently fall back to another video provider.
        creator_id:
          type: string
          format: uuid
        script:
          type: string
          minLength: 1
          description: Words the creator speaks. At most 40 words (about 15 seconds of audio).
        image_url:
          type: string
          format: uri
          description: Optional HTTP(S) image of the speaker.
        quality:
          type: string
          enum:
          - mid
          - high
          default: mid
        prompt:
          type: string
          description: Optional direction for expression and motion.
        metadata:
          type: object
          additionalProperties: true
    ReferenceBindingInput:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    ResolvedMultimodalReferenceV1:
      type: object
      additionalProperties: false
      required:
      - binding
      - asset_url
      properties:
        binding:
          $ref: '#/components/schemas/MultimodalReferenceBindingV1'
        asset_url:
          type: string
          format: uri
          description: HTTP(S) URL for the immutable asset version named by the binding.
    ApiJobResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ApiJob'
    JSONValue:
      description: Any JSON value returned by flexible workflow, analytics, context, or generation payloads.
    GenerateImageRequest:
      type: object
      required:
      - creator_id
      - prompt
      properties:
        creator_id:
          type: string
          format: uuid
        prompt:
          type: string
          minLength: 1
        visual_type:
          type: string
          enum:
          - image_quote
          - infographic
          - personal
          - profile_banner
          - profile_featured
        profile_package_id:
          type: string
          format: uuid
          description: Required for profile_banner and profile_featured; must be an active package owned by creator_id.
        profile_asset_kind:
          type: string
          enum:
          - banner
          - featured_1
          - featured_2
          description: profile_banner accepts banner; profile_featured accepts featured_1 or featured_2.
        size:
          type: string
          description: Caller-selected size for non-profile images. Profile image source sizes are enforced server-side.
        quality:
          type: string
          enum:
          - low
          - medium
          - high
          - auto
        n:
          type: integer
          minimum: 1
          maximum: 4
          description: Profile image jobs always enforce n=1.
        referenceImageUrls:
          type: array
          items:
            type: string
            format: uri
        likenessReferenceImageUrls:
          type: array
          items:
            type: string
            format: uri
        styleReferenceImageUrls:
          type: array
          items:
            type: string
            format: uri
        reference_bindings:
          type: array
          maxItems: 10
          description: Resolved official and inspiration references. Official person identity routes to likeness; other official references preserve exact product or brand truth; inspiration can guide style, layout, pose, or lighting only. The validated snapshot is persisted with the generation job.
          items:
            $ref: '#/components/schemas/ResolvedMultimodalReferenceV1'
        post_id:
          type: string
          format: uuid
          description: Optional for non-profile images. Forbidden for profile image jobs.
        alt_text:
          type: string
        metadata:
          $ref: '#/components/schemas/JSONValue'
      allOf:
      - if:
          properties:
            visual_type:
              const: profile_banner
          required:
          - visual_type
        then:
          required:
          - profile_package_id
          - profile_asset_kind
          properties:
            profile_asset_kind:
              const: banner
            n:
              const: 1
      - if:
          properties:
            visual_type:
              const: profile_featured
          required:
          - visual_type
        then:
          required:
          - profile_package_id
          - profile_asset_kind
          properties:
            profile_asset_kind:
              enum:
              - featured_1
              - featured_2
            n:
              const: 1
    GenerateVideoRequest:
      type: object
      required:
      - creator_id
      - prompt
      properties:
        creator_id:
          type: string
          format: uuid
        prompt:
          type: string
          minLength: 1
        duration:
          type: integer
          enum:
          - 5
          - 10
          default: 5
        resolution:
          type: string
          enum:
          - 480p
          - 720p
          - 1080p
          default: 720p
        aspect_ratio:
          type: string
          enum:
          - '16:9'
          - '9:16'
          - '1:1'
          default: '16:9'
        generate_audio:
          type: boolean
          default: true
        provider_policy:
          type: string
          enum:
          - automatic
          - higgsfield_only
          default: automatic
          description: Optional provider-routing constraint. higgsfield_only disables environment-forced Fal routing and automatic Fal fallback.
        image_url:
          type: string
          format: uri
          description: Optional approved start frame. When supplied, BAMF uses Seedance 2.5 image-to-video.
        reference_bindings:
          type: array
          description: Optional reference contract. The first official likeness image is used as the image-to-video start frame; inspiration references never establish identity.
          items:
            $ref: '#/components/schemas/ReferenceBindingInput'
    MultimodalReferenceBindingV1:
      type: object
      additionalProperties: false
      required:
      - schemaVersion
      - bindingId
      - workspaceId
      - subjectId
      - subjectType
      - assetId
      - assetVersion
      - authority
      - purposes
      - required
      - consent
      - provenance
      - createdAt
      properties:
        schemaVersion:
          type: string
          const: bamf.multimodal-reference-binding/v1
        bindingId:
          type: string
        workspaceId:
          type: string
        subjectId:
          type: string
        subjectType:
          type: string
          enum:
          - person
          - product
          - logo
          - typography
          - palette
          - icon
          - brand_rules
          - creator_voice
          - brand_voice
        assetId:
          type: string
        assetVersion:
          type: string
        authority:
          type: string
          enum:
          - official
          - inspiration
        purposes:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
            enum:
            - identity
            - exact_product
            - exact_logo
            - typography
            - color
            - iconography
            - brand_rules
            - voice_identity
            - voice_style
            - style
            - layout
            - pose
            - lighting
            - scale
        required:
          type: boolean
        consent:
          type: object
          required:
          - status
          - scopes
          properties:
            status:
              type: string
              enum:
              - granted
              - not_required
              - unknown
              - revoked
              - expired
            receiptRef:
              type: string
            scopes:
              type: array
              items:
                type: string
            grantedAt:
              type: string
              format: date-time
            expiresAt:
              type: string
              format: date-time
            revokedAt:
              type: string
              format: date-time
        provenance:
          type: object
          required:
          - sourceKind
          - sourceRef
          - observedAt
          properties:
            sourceKind:
              type: string
              enum:
              - upload
              - capture
              - provider_import
              - generated
              - migration
            sourceRef:
              type: string
            contentHash:
              type: string
            observedAt:
              type: string
              format: date-time
            actorRef:
              type: string
        createdAt:
          type: string
          format: date-time
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer