CraftStory Craftstory 2 API

openapi: 3.2.0
info:
  title: Craftstory Com Craftstory 2 API
  version: 1.0.0
  description: 'Operations tagged craftstory-2 across 2 of this provider''s published API definitions: craftstory-com-swagger.json, craftstory-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.craftstory.com/api/v1
security:
- ApiKey: []
tags:
- name: craftstory-2
paths:
  /craftstory-2/:
    parameters: []
    get:
      operationId: craftstory-2_list
      summary: CraftStory 2.0 — a talking video of any length from one photo and an audio clip…
      description: 'Create with ``POST``, poll ``GET /craftstory-2/{id}/status/`` until

        ``done``, then read ``video`` from ``GET /craftstory-2/{id}/``.

        Voices, cloned voices and custom avatars are listed under this prefix.'
      parameters:
      - name: ordering
        in: query
        description: 'Sort by any of the following fields: created, updated. Prefix with ''-'' for descending order.'
        schema:
          type: string
      - name: id__in
        in: query
        description: Filter by id__in
        schema:
          type: string
      - name: name
        in: query
        description: Filter by name
        schema:
          type: string
      - name: name__istartswith
        in: query
        description: Filter by name__istartswith
        schema:
          type: string
      - name: status
        in: query
        description: Filter by status
        schema:
          type: string
      - name: status__in
        in: query
        description: Filter by status__in
        schema:
          type: string
      - name: created__gte
        in: query
        description: Filter by created__gte
        schema:
          type: string
          format: date
      - name: created__lte
        in: query
        description: Filter by created__lte
        schema:
          type: string
          format: date
      - name: created__range
        in: query
        description: Filter by created__range
        schema:
          type: string
          format: date
      - name: updated__gte
        in: query
        description: Filter by updated__gte
        schema:
          type: string
          format: date
      - name: updated__lte
        in: query
        description: Filter by updated__lte
        schema:
          type: string
          format: date
      - name: updated__range
        in: query
        description: Filter by updated__range
        schema:
          type: string
          format: date
      - name: resolution
        in: query
        description: Filter by resolution
        schema:
          type: string
      - name: gestures
        in: query
        description: Filter by gestures
        schema:
          type: string
      - name: lipsync_mode
        in: query
        description: Filter by lipsync_mode
        schema:
          type: string
      - name: search
        in: query
        description: A search term.
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return per page.
        required: false
        schema:
          type: integer
      - name: offset
        in: query
        description: The initial index from which to return the results.
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CraftStory2'
      tags:
      - craftstory-2
    post:
      operationId: craftstory-2_create
      summary: Start a CraftStory 2.0 generation
      description: 'Multipart or JSON. ``image`` (file or URL) or ``scene_id`` selects the

        driving photo; ``audios`` (ids from ``/audio/clips/``) sets the speech

        and the length. Credits are charged up front and refunded on failure.'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CraftStory2'
      tags:
      - craftstory-2
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CraftStory2Create'
        required: true
    servers:
    - url: https://api.craftstory.com/api/v1
  /craftstory-2/avatars/:
    parameters: []
    get:
      operationId: craftstory-2_avatars
      summary: List the caller's custom avatars usable as ``avatar_id``
      description: 'Returns avatars visible to the user (system + owned-ready + shared-ready)

        that have a trained model — exactly the set accepted on create. Pass an

        ``id`` from here as ``avatar_id`` in ``POST /api/v1/craftstory-2/`` to

        generate with that custom avatar.'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AvatarPublic'
      tags:
      - craftstory-2
    servers:
    - url: https://api.craftstory.com/api/v1
  /craftstory-2/avatars/{avatar_pk}/scenes/:
    parameters:
    - name: avatar_pk
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: craftstory-2_avatars_avatar_scenes
      summary: List the scenes of one custom avatar visible to the caller
      description: 'Use a scene ``id`` from here as ``scene_id`` in

        ``POST /api/v1/craftstory-2/`` — an alternative to uploading an

        ``image``. ``image_url`` is a signed preview link.

        Returns 404 if the avatar is not visible to the caller.'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AvatarScenePublic'
      tags:
      - craftstory-2
    servers:
    - url: https://api.craftstory.com/api/v1
  /craftstory-2/preview-cost/:
    parameters: []
    post:
      operationId: craftstory-2_preview_cost
      description: Return the expected credit cost without creating a task.
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CraftStory2PreviewCostResponse'
      tags:
      - craftstory-2
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CraftStory2PreviewCost'
        required: true
      summary: Craftstory 2 preview cost
      x-summary-source: derived
    servers:
    - url: https://api.craftstory.com/api/v1
  /craftstory-2/user-voices/:
    parameters: []
    get:
      operationId: craftstory-2_user_voices
      summary: List your cloned (custom) voices that are ready to use
      description: 'Pass a voice ``id`` from here as ``voice_user_id`` on

        ``POST /api/v1/audio/clips/`` to generate audio in that voice.'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserVoicePublic'
      tags:
      - craftstory-2
    servers:
    - url: https://api.craftstory.com/api/v1
  /craftstory-2/voices/:
    parameters: []
    get:
      operationId: craftstory-2_voices
      summary: List built-in library voices
      description: 'Pass a voice ``id`` from here as ``voice_id`` on

        ``POST /api/v1/audio/clips/`` to generate audio in that voice.'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LibraryVoicePublic'
      tags:
      - craftstory-2
    servers:
    - url: https://api.craftstory.com/api/v1
  /craftstory-2/{id}/:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: craftstory-2_read
      summary: CraftStory 2.0 — a talking video of any length from one photo and an audio clip…
      description: 'Create with ``POST``, poll ``GET /craftstory-2/{id}/status/`` until

        ``done``, then read ``video`` from ``GET /craftstory-2/{id}/``.

        Voices, cloned voices and custom avatars are listed under this prefix.'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CraftStory2'
      tags:
      - craftstory-2
    delete:
      operationId: craftstory-2_delete
      summary: CraftStory 2.0 — a talking video of any length from one photo and an audio clip…
      description: 'Create with ``POST``, poll ``GET /craftstory-2/{id}/status/`` until

        ``done``, then read ``video`` from ``GET /craftstory-2/{id}/``.

        Voices, cloned voices and custom avatars are listed under this prefix.'
      responses:
        '204':
          description: ''
      tags:
      - craftstory-2
    servers:
    - url: https://api.craftstory.com/api/v1
  /craftstory-2/{id}/asset/:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: craftstory-2_create_asset
      summary: CraftStory 2.0 — a talking video of any length from one photo and an audio clip…
      description: 'Create with ``POST``, poll ``GET /craftstory-2/{id}/status/`` until

        ``done``, then read ``video`` from ``GET /craftstory-2/{id}/``.

        Voices, cloned voices and custom avatars are listed under this prefix.'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetListRetrieve'
      tags:
      - craftstory-2
    servers:
    - url: https://api.craftstory.com/api/v1
  /craftstory-2/{id}/status/:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: craftstory-2_get_status
      summary: CraftStory 2.0 — a talking video of any length from one photo and an audio clip…
      description: 'Create with ``POST``, poll ``GET /craftstory-2/{id}/status/`` until

        ``done``, then read ``video`` from ``GET /craftstory-2/{id}/``.

        Voices, cloned voices and custom avatars are listed under this prefix.'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CraftStory2Status'
      tags:
      - craftstory-2
    servers:
    - url: https://api.craftstory.com/api/v1
  /craftstory-2/{id}/upscale/:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: craftstory-2_make_upscale
      description: Upscale a finished video to 1080p as a new record (0.2 credits/s).
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CraftStory2'
      tags:
      - craftstory-2
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CraftStory2Upscale'
        required: true
      summary: Craftstory 2 make upscale
      x-summary-source: derived
    servers:
    - url: https://api.craftstory.com/api/v1
components:
  schemas:
    CraftStory2PreviewCost:
      required:
      - audios
      - resolution
      type: object
      properties:
        audios:
          type: array
          items:
            type: string
            format: uuid
          uniqueItems: true
        resolution:
          title: Resolution
          type: string
          enum:
          - '480_832'
          - '832_480'
          - '720_1280'
          - '1280_720'
          - '768_960'
        lipsync_mode:
          title: Lipsync mode
          description: 'Lipsync engine: sync_so (default, same price), craftstory (built-in), empty (off).'
          type: string
          enum:
          - craftstory
          - sync_so
          - empty
          default: sync_so
    UserVoicePublic:
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
          readOnly: true
        name:
          title: Name
          type: string
          maxLength: 256
        language:
          title: Language
          type:
          - string
          - 'null'
          readOnly: true
        gender:
          title: Gender
          type:
          - string
          - 'null'
          enum:
          - male
          - female
          - null
        age:
          title: Age
          type:
          - string
          - 'null'
          enum:
          - child
          - young_adult
          - middle_adult
          - old
          - null
        example:
          title: Example
          type:
          - string
          - 'null'
          readOnly: true
    CraftStory2Status:
      type: object
      properties:
        status:
          title: Status
          type: string
          enum:
          - created
          - in_progress_converting_image20_to_png
          - in_progress_audio
          - in_progress_10_video_queued
          - in_progress_10_video_generating
          - in_progress_20_video_queued
          - in_progress_moderation_image
          - in_progress_20_video_generating
          - in_progress_upscaling_queued
          - in_progress_upscaling_generating
          - failed
          - done
          - rejected_image
        status_failed:
          title: Status failed
          type:
          - string
          - 'null'
          enum:
          - video10_generating
          - convert_image20_to_png
          - failed_image_moderation
          - rejected_image
          - failed_join_audios
          - video20_first_frame
          - no_person_detected_image
          - no_person_detected_video
          - multiple_people_detected_image
          - no_face_detected_image
          - failed_image
          - failed_video
          - gpu_unavailable
          - failed_outpaint
          - failed_lipsync
          - null
        status_failed_display:
          title: Status failed display
          type: string
          readOnly: true
        status_percentage:
          title: Status percentage
          type: integer
          maximum: 32767
          minimum: 0
        credits_refunded:
          title: Credits refunded
          type: string
          readOnly: true
    CraftStory2Upscale:
      required:
      - resolution
      type: object
      properties:
        resolution:
          title: Resolution
          description: 1080_1920 for a 720_1280 source, 1920_1080 for a 1280_720 source, 1152_1440 for a 768_960 source.
          type: string
          enum:
          - '1080_1920'
          - '1920_1080'
          - '1152_1440'
        credits:
          title: Credits
          type: integer
          readOnly: true
    AvatarScenePublic:
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
          readOnly: true
        image_url:
          title: Image url
          type:
          - string
          - 'null'
          readOnly: true
    AssetListRetrieveProject:
      required:
      - name
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
          readOnly: true
        name:
          title: Name
          type: string
          maxLength: 512
          minLength: 1
    CraftStory2Create:
      required:
      - audios
      - resolution
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
          readOnly: true
        name:
          title: Name
          type:
          - string
          - 'null'
          maxLength: 512
        image:
          title: Image
          description: 'Driving photo: file upload or URL. Provide image or scene_id (if both, scene_id wins).'
          type: string
          readOnly: true
          format: uri
        scene_id:
          title: Scene id
          description: Avatar scene id (from GET /craftstory-2/avatars/{id}/scenes/); its image becomes the driving frame. Provide scene_id or image (if both, scene_id wins).
          type:
          - string
          - 'null'
          format: uuid
        audios:
          type: array
          items:
            type: string
            format: uuid
          uniqueItems: true
        gestures:
          title: Gestures
          description: 'How much the avatar moves: normal (default), calm, expressive.'
          type: string
          enum:
          - normal
          - calm
          - expressive
          default: normal
        resolution:
          title: Resolution
          description: 'Output size WIDTH_HEIGHT: 9:16 / 16:9 at 480p or 720p, or 768_960 for 4:5 portrait (audio under 30 minutes). A 1.5x upscale is available via /upscale/ afterwards.'
          type: string
          enum:
          - '480_832'
          - '832_480'
          - '720_1280'
          - '1280_720'
          - '768_960'
        lipsync_mode:
          title: Lipsync mode
          description: 'Lipsync engine: sync_so (default, same price), craftstory (built-in), empty (off).'
          type: string
          enum:
          - craftstory
          - sync_so
          - empty
          default: sync_so
        user_prompt:
          title: User prompt
          description: Optional motion / scene hint in free text (gestures, expressions, camera).
          type: string
          maxLength: 1000
        avatar_id:
          title: Avatar id
          description: Optional custom avatar id (from GET /craftstory-2/avatars/); its trained model drives identity.
          type:
          - string
          - 'null'
          format: uuid
        faceswap:
          title: Faceswap
          description: Optional — defaults to true (recommended). With avatar_id the default flips to false (the trained avatar already carries identity); an explicit value is honoured either way.
          type: boolean
          default: true
        credits:
          title: Credits
          type: integer
          readOnly: true
    LibraryVoicePublic:
      required:
      - name
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
          readOnly: true
        name:
          title: Name
          type: string
          maxLength: 256
          minLength: 1
        language:
          title: Language
          type:
          - string
          - 'null'
          readOnly: true
        gender:
          title: Gender
          type:
          - string
          - 'null'
          enum:
          - male
          - female
          - null
        age:
          title: Age
          type:
          - string
          - 'null'
          enum:
          - child
          - young_adult
          - middle_adult
          - old
          - null
        labels:
          type: array
          items:
            type: string
          readOnly: true
        example:
          title: Example
          type:
          - string
          - 'null'
          readOnly: true
    CraftStory2:
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
          readOnly: true
        name:
          title: Name
          type:
          - string
          - 'null'
          readOnly: true
          minLength: 1
        kind:
          title: Kind
          type: string
          enum:
          - regular
          - upscale
          - clone
          - studio
          readOnly: true
        status:
          title: Status
          type: string
          enum:
          - created
          - in_progress_converting_image20_to_png
          - in_progress_audio
          - in_progress_10_video_queued
          - in_progress_10_video_generating
          - in_progress_20_video_queued
          - in_progress_moderation_image
          - in_progress_20_video_generating
          - in_progress_upscaling_queued
          - in_progress_upscaling_generating
          - failed
          - done
          - rejected_image
          readOnly: true
        status_failed:
          title: Status failed
          type:
          - string
          - 'null'
          enum:
          - video10_generating
          - convert_image20_to_png
          - failed_image_moderation
          - rejected_image
          - failed_join_audios
          - video20_first_frame
          - no_person_detected_image
          - no_person_detected_video
          - multiple_people_detected_image
          - no_face_detected_image
          - failed_image
          - failed_video
          - gpu_unavailable
          - failed_outpaint
          - failed_lipsync
          - null
          readOnly: true
        status_failed_display:
          title: Status failed display
          type: string
          readOnly: true
        status_percentage:
          title: Status percentage
          type: integer
          readOnly: true
        credits_refunded:
          title: Credits refunded
          type: string
          readOnly: true
        audios:
          type: array
          items:
            type: string
            format: uuid
          readOnly: true
          uniqueItems: true
        image:
          title: Image
          type: string
          readOnly: true
          format: uri
        gestures:
          title: Gestures
          type: string
          readOnly: true
          minLength: 1
        resolution:
          title: Resolution
          type: string
          readOnly: true
          minLength: 1
        lipsync_mode:
          title: Lipsync mode
          description: 'Lipsync engine: sync_so (default, same price), craftstory (built-in), empty (off).'
          type: string
          enum:
          - craftstory
          - sync_so
          - empty
          readOnly: true
        user_prompt:
          title: User prompt
          type: string
          readOnly: true
          minLength: 1
        video:
          title: Video
          description: Result MP4; null until status is done.
          type: string
          readOnly: true
          format: uri
        video_duration_s:
          title: Video duration s
          description: Length of the result in seconds; null until done.
          type:
          - number
          - 'null'
          readOnly: true
        video_first_frame:
          title: Video first frame
          type: string
          readOnly: true
          format: uri
        credits:
          title: Credits
          type: integer
          readOnly: true
        asset:
          title: Asset
          type:
          - string
          - 'null'
          format: uuid
          readOnly: true
        created:
          title: Created
          type: string
          format: date-time
          readOnly: true
        updated:
          title: Updated
          type: string
          format: date-time
          readOnly: true
    AvatarPublic:
      required:
      - name
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
          readOnly: true
        name:
          title: Name
          type: string
          maxLength: 128
          minLength: 1
        cover_url:
          title: Cover url
          type:
          - string
          - 'null'
          readOnly: true
        scene_count:
          title: Scene count
          type: integer
          readOnly: true
        voice:
          title: Voice
          type:
          - object
          - 'null'
          readOnly: true
        models:
          type: array
          items:
            type: string
          readOnly: true
    AssetListRetrieve:
      required:
      - project
      - kind
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
          readOnly: true
        project:
          $ref: '#/components/schemas/AssetListRetrieveProject'
        kind:
          title: Kind
          type: string
          enum:
          - audio
          - image
          - video
          - image_ppx
          - image_llm
          - video_llm
          - video_video2video
          - video_image2video
          - video_audio2video
          - video_cloudvideo
          - image_marketing
          - video_marketing
        status:
          title: Status
          type: string
          enum:
          - created
          - pending
          - done
          - failed
          - rejected
        status_display:
          title: Status display
          type: string
          readOnly: true
        moderation_labels:
          title: Moderation labels
          type:
          - object
          - 'null'
        is_approved:
          title: Is approved
          type: boolean
        file:
          title: File
          type:
          - string
          - 'null'
          readOnly: true
          format: uri
        data:
          title: Data
          type:
          - object
          - 'null'
        schema:
          title: Schema
          type:
          - object
          - 'null'
        order:
          title: Order
          type: integer
          maximum: 32767
          minimum: 0
        created:
          title: Created
          type: string
          format: date-time
          readOnly: true
        updated:
          title: Updated
          type: string
          format: date-time
          readOnly: true
        first_frame_1000:
          title: First frame 1000
          type:
          - string
          - 'null'
          readOnly: true
    CraftStory2PreviewCostResponse:
      required:
      - credits
      type: object
      properties:
        credits:
          title: Credits
          type: integer
    CraftStory2PreviewCost_2:
      required:
      - audios
      - resolution
      type: object
      properties:
        audios:
          type: array
          items:
            type: string
            format: uuid
          uniqueItems: true
        resolution:
          title: Resolution
          type: string
          enum:
          - 480832
          - 832480
          - 7201280
          - 1280720
          - 768960
        lipsync_mode:
          title: Lipsync mode
          description: 'Lipsync engine: sync_so (default, same price), craftstory (built-in), empty (off).'
          type: string
          enum:
          - craftstory
          - sync_so
          - empty
          default: sync_so
    CraftStory2Upscale_2:
      required:
      - resolution
      type: object
      properties:
        resolution:
          title: Resolution
          description: 1080_1920 for a 720_1280 source, 1920_1080 for a 1280_720 source, 1152_1440 for a 768_960 source.
          type: string
          enum:
          - 10801920
          - 19201080
          - 11521440
        credits:
          title: Credits
          type: integer
          readOnly: true
    CraftStory2Create_2:
      required:
      - audios
      - resolution
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
          readOnly: true
        name:
          title: Name
          type:
          - string
          - 'null'
          maxLength: 512
        image:
          title: Image
          description: 'Driving photo: file upload or URL. Provide image or scene_id (if both, scene_id wins).'
          type: string
          readOnly: true
          format: uri
        scene_id:
          title: Scene id
          description: Avatar scene id (from GET /craftstory-2/avatars/{id}/scenes/); its image becomes the driving frame. Provide scene_id or image (if both, scene_id wins).
          type:
          - string
          - 'null'
          format: uuid
        audios:
          type: array
          items:
            type: string
            format: uuid
          uniqueItems: true
        gestures:
          title: Gestures
          description: 'How much the avatar moves: normal (default), calm, expressive.'
          type: string
          enum:
          - normal
          - calm
          - expressive
          default: normal
        resolution:
          title: Resolution
          description: 'Output size WIDTH_HEIGHT: 9:16 / 16:9 at 480p or 720p, or 768_960 for 4:5 portrait (audio under 30 minutes). A 1.5x upscale is available via /upscale/ afterwards.'
          type: string
          enum:
          - 480832
          - 832480
          - 7201280
          - 1280720
          - 768960
        lipsync_mode:
          title: Lipsync mode
          description: 'Lipsync engine: sync_so (default, same price), craftstory (built-in), empty (off).'
          type: string
          enum:
          - craftstory
          - sync_so
          - empty
          default: sync_so
        user_prompt:
          title: User prompt
          description: Optional motion / scene hint in free text (gestures, expressions, camera).
          type: string
          maxLength: 1000
        avatar_id:
          title: Avatar id
          description: Optional custom avatar id (from GET /craftstory-2/avatars/); its trained model drives identity.
          type:
          - string
          - 'null'
          format: uuid
        faceswap:
          title: Faceswap
          description: Optional — defaults to true (recommended). With avatar_id the default flips to false (the trained avatar already carries identity); an explicit value is honoured either way.
          type: boolean
          default: true
        credits:
          title: Credits
          type: integer
          readOnly: true
  securitySchemes:
    ApiKey:
      type: apiKey
      name: Authorization
      in: header
      description: Enter 'Bearer sk-cs-...' (your API key from Account → API Access).
x-refined-from:
- craftstory-com-swagger.json
- craftstory-com-openapi.yml