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

# Create jobs

> Generate, try on, edit, inpaint, upscale, or create video with one submission and response format.

Choose an `operation` and put its settings in `input`. For edit, inpaint, upscale, and image-to-video, set `image_id` to the source image. Generate and try-on references belong inside `input`.

Unknown envelope and input fields are rejected. The JSON body must be no larger than 2 MiB.

Each entry in `jobs` is the actual new processing job, including operations that also create an image version. Save every `id` and [poll the job](/api-reference/jobs/get).

[Track jobs and image versions →](/api-reference/jobs-and-versions)


## OpenAPI

````yaml POST /v1/jobs
openapi: 3.0.3
info:
  title: bitStudio API
  version: '2026-09-06'
  description: >-
    Core Studio image, video, and reusable-asset workflows. Requests use a
    workspace-scoped API key and the account’s feature access and credits.
    Generation is asynchronous.
  contact:
    name: bitStudio support
    email: hello@bitstudio.ai
servers:
  - url: https://api.bitstudio.ai
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Images
  - name: Video
  - name: Assets
paths:
  /v1/jobs:
    post:
      tags:
        - Jobs
      summary: Create image or video jobs
      description: >-
        Submit one operation. Every accepted request returns 202 with a jobs
        array containing the actual new processing jobs. Uses the existing
        operation-specific validation, credits, and permissions. JSON bodies are
        limited to 2 MiB; unknown envelope or input fields are rejected. Do not
        automatically retry a timed-out POST; idempotency keys are not
        supported.
      operationId: createJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobSubmission'
            examples:
              generate:
                summary: generate
                value:
                  operation: generate
                  input:
                    model_version: nano-banana-2
                    generate_mode: presets
                    model_text: An adult fashion model
                    outfit_image_ids:
                      - 11111111-1111-4111-8111-111111111111
                    prompt: Full-length front view in a white studio, soft shadows.
                    resolution: standard
                    aspect_ratio: '3:4'
                    num_images: 1
              virtual-try-on:
                summary: virtual-try-on
                value:
                  operation: virtual-try-on
                  input:
                    person_image_id: 11111111-1111-4111-8111-111111111111
                    outfit_asset_id: 22222222-2222-4222-8222-222222222222
                    model: nano-banana-2
                    resolution: standard
                    num_images: 1
                    speed: fast
              edit:
                summary: edit
                value:
                  operation: edit
                  input:
                    prompt: >-
                      Use a warm off-white studio background. Keep the person
                      and suit unchanged.
                    model: nano-banana-2
                    resolution: standard
                    num_images: 1
                  image_id: 11111111-1111-4111-8111-111111111111
              inpaint:
                summary: inpaint
                value:
                  operation: inpaint
                  input:
                    mask_image_id: 33333333-3333-4333-8333-333333333333
                    prompt: Continue the plain studio wall.
                    model: v1
                    resolution: standard
                    num_images: 1
                    denoise: 0.75
                  image_id: 11111111-1111-4111-8111-111111111111
              upscale:
                summary: upscale
                value:
                  operation: upscale
                  input:
                    upscale_factor: 2
                    denoise: 0.2
                  image_id: 11111111-1111-4111-8111-111111111111
              image-to-video:
                summary: image-to-video
                value:
                  operation: image-to-video
                  input:
                    model: kling-v3-pro
                    prompt: Slow camera push-in. The model holds a steady pose.
                    duration: 5
                    generate_audio: false
                  image_id: 11111111-1111-4111-8111-111111111111
              text-to-video:
                summary: text-to-video
                value:
                  operation: text-to-video
                  input:
                    model: kling-v3-standard
                    prompt: >-
                      A fashion model standing in a pale studio, slow camera
                      push-in.
                    duration: 5
                    aspect_ratio: '9:16'
                    generate_audio: false
      responses:
        '202':
          description: Accepted for asynchronous processing.
          content:
            application/json:
              schema:
                type: object
                required:
                  - jobs
                properties:
                  jobs:
                    type: array
                    items:
                      $ref: '#/components/schemas/Job'
              example:
                jobs:
                  - id: 33333333-3333-4333-8333-333333333333
                    status: pending
                    task: generate
                    created_at: '2026-09-06T12:00:00Z'
                    result: null
                    error: null
        default:
          description: >-
            Request rejected or service error. See the errors and recovery
            guide.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    JobSubmission:
      oneOf:
        - title: generate
          type: object
          additionalProperties: false
          required:
            - operation
            - input
          properties:
            operation:
              type: string
              enum:
                - generate
            input:
              $ref: '#/components/schemas/GenerateInput'
        - title: virtual-try-on
          type: object
          additionalProperties: false
          required:
            - operation
            - input
          properties:
            operation:
              type: string
              enum:
                - virtual-try-on
            input:
              $ref: '#/components/schemas/TryOnInput'
        - title: edit
          type: object
          additionalProperties: false
          required:
            - operation
            - input
            - image_id
          properties:
            operation:
              type: string
              enum:
                - edit
            input:
              $ref: '#/components/schemas/EditInput'
            image_id:
              type: string
              format: uuid
              description: >-
                Source image ID. To use a parent’s specific version, also set
                input.version_id.
        - title: inpaint
          type: object
          additionalProperties: false
          required:
            - operation
            - input
            - image_id
          properties:
            operation:
              type: string
              enum:
                - inpaint
            input:
              $ref: '#/components/schemas/InpaintInput'
            image_id:
              type: string
              format: uuid
              description: >-
                Source image ID. To use a parent’s specific version, also set
                input.version_id.
        - title: upscale
          type: object
          additionalProperties: false
          required:
            - operation
            - input
            - image_id
          properties:
            operation:
              type: string
              enum:
                - upscale
            input:
              $ref: '#/components/schemas/UpscaleInput'
            image_id:
              type: string
              format: uuid
              description: >-
                Source image ID. To use a parent’s specific version, also set
                input.version_id.
        - title: image-to-video
          type: object
          additionalProperties: false
          required:
            - operation
            - input
            - image_id
          properties:
            operation:
              type: string
              enum:
                - image-to-video
            input:
              $ref: '#/components/schemas/VideoInput'
            image_id:
              type: string
              format: uuid
              description: >-
                Source image ID. To use a parent’s specific version, also set
                input.version_id.
        - title: text-to-video
          type: object
          additionalProperties: false
          required:
            - operation
            - input
          properties:
            operation:
              type: string
              enum:
                - text-to-video
            input:
              $ref: '#/components/schemas/TextVideoInput'
    Job:
      type: object
      required:
        - id
        - status
        - task
        - created_at
        - result
        - error
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - pending
            - generating
            - completed
            - failed
            - policy_blocked
        task:
          type: string
          nullable: true
          description: >-
            Processing task. This may be more specific than the submitted
            operation.
        created_at:
          type: string
          format: date-time
        result:
          $ref: '#/components/schemas/JobResult'
        error:
          $ref: '#/components/schemas/JobError'
    Error:
      type: object
      properties:
        error:
          type: string
          description: Some handlers return a plain error string.
        code:
          type: string
          description: Structured error code, when available.
        message:
          type: string
          description: Structured human-readable error, when available.
        cta:
          type: boolean
          description: Whether the response includes an account action.
        next_action:
          type: string
          description: Suggested action, such as a plan or credit change.
        current_plan:
          type: string
          description: ''
        user_message:
          type: string
          description: User-facing explanation when present.
        extra_context:
          type: string
          description: Additional error context when present.
      description: >-
        Error shapes differ by endpoint. Read message or error; preserve the
        HTTP status and code. Additional context fields may be returned.
    GenerateInput:
      type: object
      properties:
        asset_ids:
          type: array
          items:
            type: string
            description: Resource ID.
            format: uuid
          description: >-
            Avatar, preset, pose, set, or style asset IDs. Use at most one
            preset or set in total.
        outfit_asset_ids:
          type: array
          items:
            type: string
            description: Resource ID.
            format: uuid
          description: Reusable outfit references. Use one source form per product.
          maxItems: 3
        outfit_image_ids:
          type: array
          items:
            type: string
            description: Resource ID.
            format: uuid
          description: Previously uploaded garment images.
          maxItems: 3
        outfit_image_urls:
          type: array
          items:
            type: string
            description: ''
            format: uri
          description: Direct garment image URLs accessible to the service.
          maxItems: 3
        outfit_asset_id:
          type: string
          description: Single-outfit alternative to outfit_asset_ids.
          format: uuid
        outfit_image_id:
          type: string
          description: Single-image alternative to outfit_image_ids.
          format: uuid
        outfit_image_url:
          type: string
          description: Single-URL alternative to outfit_image_urls.
          format: uri
        prompt:
          type: string
          description: Composition or extra preset directions.
        model_text:
          type: string
          description: Describe the avatar when not selecting one from the library.
        outfit_text:
          type: string
          description: How the selected garment should be worn.
        set_text:
          type: string
          description: Setting directions when needed.
        generate_mode:
          type: string
          description: Use presets for the standard reference workflow.
          enum:
            - presets
            - legacy
          example: presets
        model_version:
          type: string
          description: >-
            Image model identifier. nano-banana-2 is used in this guide;
            availability depends on your account.
          example: nano-banana-2
        resolution:
          type: string
          description: >-
            Output quality. Send explicitly. Pixel dimensions depend on the
            image model.
          enum:
            - standard
            - high
          example: standard
        aspect_ratio:
          type: string
          description: >-
            Model-dependent output ratio. 3:4 is supported by nano-banana-2 and
            nano-banana-pro.
          example: '3:4'
        num_images:
          type: integer
          description: Number of outputs. Defaults to 1. Account limits still apply.
          minimum: 1
          maximum: 8
          example: 1
          default: 1
        seed:
          type: integer
          description: >-
            Optional seed. It does not guarantee identical results across models
            or changes.
        tutorial_id:
          type: string
          description: Studio onboarding identifier. Omit for normal generation.
        style:
          type: string
          description: Optional style directions.
        style_id:
          type: string
          description: Optional saved style asset ID.
        set_id:
          type: string
          description: >-
            Legacy set asset ID. Prefer a preset in asset_ids for the standard
            workflow.
        set_mode:
          type: string
          description: >-
            Legacy scene mode. Use generate_mode: presets for the standard
            workflow.
      required:
        - resolution
      additionalProperties: false
    TryOnInput:
      type: object
      properties:
        person_image_id:
          type: string
          description: Uploaded person image. Supply this or person_image_url.
          format: uuid
        person_image_url:
          type: string
          description: Direct URL of a person photo.
          format: uri
        person_version_id:
          type: string
          description: Optional source version belonging to person_image_id.
          format: uuid
        outfit_asset_id:
          type: string
          description: Reusable outfit asset. Supply an outfit asset, image, or URL.
          format: uuid
        outfit_image_id:
          type: string
          description: Uploaded garment image.
          format: uuid
        outfit_image_url:
          type: string
          description: Direct garment photo URL.
          format: uri
        outfit_asset_ids:
          type: array
          items:
            type: string
            description: Resource ID.
            format: uuid
          description: Multiple garment assets; supported models only.
          maxItems: 3
        outfit_image_ids:
          type: array
          items:
            type: string
            description: Resource ID.
            format: uuid
          description: Multiple garment uploads; supported models only.
          maxItems: 3
        outfit_image_urls:
          type: array
          items:
            type: string
            description: ''
            format: uri
          description: Multiple garment URLs; supported models only.
          maxItems: 3
        model:
          type: string
          description: >-
            Use nano-banana-2 for this example. Other model availability and
            multi-outfit support vary.
          example: nano-banana-2
        resolution:
          type: string
          description: >-
            Output quality. Send explicitly. Pixel dimensions depend on the
            image model.
          enum:
            - standard
            - high
          example: standard
          default: standard
        num_images:
          type: integer
          description: Number of outputs. Defaults to 1. Account limits still apply.
          minimum: 1
          maximum: 8
          example: 1
          default: 1
        prompt:
          type: string
          description: Optional styling instructions.
        speed:
          type: string
          description: >-
            Processing option. fast is used in the example; accepted values
            depend on the model.
          example: fast
        create_version:
          type: boolean
          description: >-
            false returns an array of new jobs. true links a version to the
            person image and returns that parent image.
          default: false
        asset_ids:
          type: array
          items:
            type: string
          description: >-
            Additional reusable reference asset IDs. Supported types depend on
            the operation.
        aspect_ratio:
          type: string
          description: Optional model-dependent output ratio.
        style:
          type: string
          description: Optional style directions.
        seed:
          type: integer
          description: Optional seed; it does not guarantee identical results.
        cf_turnstile_response:
          type: string
          description: Embedded storefront metadata. Omit for standard Studio integrations.
        shopify_product_id:
          type: string
          description: Embedded storefront metadata. Omit for standard Studio integrations.
        shopify_customer_id:
          type: string
          description: Embedded storefront metadata. Omit for standard Studio integrations.
        shopify_product_handle:
          type: string
          description: Embedded storefront metadata. Omit for standard Studio integrations.
        shopify_product_title:
          type: string
          description: Embedded storefront metadata. Omit for standard Studio integrations.
        customer_email:
          type: string
          description: Embedded storefront metadata. Omit for standard Studio integrations.
      additionalProperties: false
    EditInput:
      type: object
      properties:
        prompt:
          type: string
          description: Describe the requested change.
          minLength: 1
        version_id:
          type: string
          description: >-
            Optional version of this image to use as the source. Omit to use the
            original image.
          format: uuid
        model:
          type: string
          description: Image model used for the edit.
          example: nano-banana-2
        resolution:
          type: string
          description: >-
            Output quality. Send explicitly. Pixel dimensions depend on the
            image model.
          enum:
            - standard
            - high
          example: standard
        num_images:
          type: integer
          description: Number of outputs. Defaults to 1. Account limits still apply.
          minimum: 1
          maximum: 1
          example: 1
          default: 1
        aspect_ratio:
          type: string
          description: Optional target ratio, especially for extend.
        task:
          type: string
          description: Kind of edit. Feature and model availability vary.
          enum:
            - edit
            - pose-change
            - face-swap
            - extend
          default: edit
        reference_image_id:
          type: string
          description: Optional image reference. Do not combine with reference_asset_id.
          format: uuid
        reference_asset_id:
          type: string
          description: >-
            Optional reusable asset reference. Do not combine with
            reference_image_id.
          format: uuid
        reference_image_ids:
          type: array
          items:
            type: string
            description: Resource ID.
            format: uuid
          description: Multiple image references for text edits.
          maxItems: 3
        reference_asset_ids:
          type: array
          items:
            type: string
            description: Resource ID.
            format: uuid
          description: Multiple asset references for text edits.
          maxItems: 3
        seed:
          type: integer
          description: ''
        speed:
          type: string
          description: >-
            Optional processing speed; accepted values depend on the operation
            and model.
      required:
        - prompt
        - resolution
      additionalProperties: false
    InpaintInput:
      type: object
      properties:
        mask_image_id:
          type: string
          description: >-
            Uploaded black-and-white PNG mask: white marks the region to change;
            black preserves the surrounding area. Must match the selected source
            dimensions.
          format: uuid
        version_id:
          type: string
          description: >-
            Optional version of this image to use as the source. Omit to use the
            original image.
          format: uuid
        prompt:
          type: string
          description: What should appear in the masked area.
        resolution:
          type: string
          description: >-
            Output quality. Send explicitly. Pixel dimensions depend on the
            image model.
          enum:
            - standard
            - high
          example: standard
        num_images:
          type: integer
          description: Number of outputs. Defaults to 1. Account limits still apply.
          minimum: 1
          maximum: 1
          example: 1
          default: 1
        denoise:
          type: number
          minimum: 0.05
          maximum: 1
          description: Strength of the change. Send explicitly.
          example: 0.75
        model:
          type: string
          description: Inpaint currently supports v1.
          enum:
            - v1
          default: v1
        reference_image_id:
          type: string
          description: Optional reference, mutually exclusive with reference_asset_id.
          format: uuid
        reference_asset_id:
          type: string
          description: >-
            Optional reusable reference, mutually exclusive with
            reference_image_id.
          format: uuid
        asset_ids:
          type: array
          items:
            type: string
          description: >-
            Additional reusable reference asset IDs. Supported types depend on
            the operation.
        style:
          type: string
          description: Optional style directions.
        seed:
          type: integer
          description: Optional seed; it does not guarantee identical results.
        speed:
          type: string
          description: >-
            Optional processing speed; accepted values depend on the operation
            and model.
        task:
          type: string
          description: Processing task override. Omit for a standard inpaint operation.
      required:
        - mask_image_id
        - resolution
        - denoise
      additionalProperties: false
    UpscaleInput:
      type: object
      properties:
        version_id:
          type: string
          description: >-
            Optional version of this image to use as the source. Omit to use the
            original image.
          format: uuid
        upscale_factor:
          type: integer
          description: >-
            Upscale option. 4 selects the 4K workflow; do not assume it
            literally multiplies both dimensions by four.
          enum:
            - 1
            - 2
            - 4
          example: 2
        denoise:
          type: number
          minimum: 0
          maximum: 1
          description: Detail-change strength.
          example: 0.2
      required:
        - upscale_factor
      additionalProperties: false
    VideoInput:
      type: object
      properties:
        prompt:
          type: string
          description: Scene and motion direction.
        model:
          type: string
          description: >-
            Kling 3 returns a standalone job. Kling 2.5 image-to-video returns
            the parent image with a linked version.
          enum:
            - kling-2.5
            - kling-v3-pro
            - kling-v3-standard
          example: kling-v3-pro
        duration:
          type: integer
          description: >-
            Clip duration in seconds. Use 5 for the first request. Supported
            durations depend on the model.
          example: 5
        aspect_ratio:
          type: string
          description: Video output ratio.
          enum:
            - '16:9'
            - '9:16'
            - '1:1'
        generate_audio:
          type: boolean
          description: Generated audio for models that support it.
          default: false
        multi_prompt:
          type: array
          items:
            type: object
            properties:
              prompt:
                type: string
                description: Directions for this shot.
              duration:
                type: integer
                description: Shot length in seconds.
                minimum: 3
                maximum: 15
            required:
              - prompt
              - duration
            additionalProperties: false
          description: >-
            Kling 3 multi-shot directions. The shot durations determine the
            total duration. Use a single prompt first.
        negative_prompt:
          type: string
          description: Optional undesired visual characteristics.
        version_id:
          type: string
          description: >-
            Optional version of this image to use as the source. Omit to use the
            original image.
          format: uuid
        last_frame_id:
          type: string
          description: >-
            Optional end frame. Its dimensions must match the start frame.
            Mutually exclusive with last_frame_url.
          format: uuid
        last_frame_url:
          type: string
          description: Direct end-frame URL. The same media constraints apply.
          format: uri
        resolution:
          type: string
          description: Optional output quality; supported values depend on the video model.
        elements:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              asset_id:
                type: string
                format: uuid
              frontal_image_id:
                type: string
                format: uuid
              frontal_image_url:
                type: string
                format: uri
              reference_image_ids:
                type: array
                items:
                  type: string
                  format: uuid
              reference_image_urls:
                type: array
                items:
                  type: string
                  format: uri
          description: >-
            Kling 3 subject references. Provide an asset or direct image
            references for each element.
        avatar_text:
          type: string
          description: Additional avatar directions for supported video models.
        outfit_text:
          type: string
          description: Additional outfit directions for supported video models.
      additionalProperties: false
    TextVideoInput:
      type: object
      properties:
        prompt:
          type: string
          description: Scene and motion direction.
        model:
          type: string
          description: Text-to-video model.
          enum:
            - kling-v3-pro
            - kling-v3-standard
          example: kling-v3-standard
        duration:
          type: integer
          description: >-
            Clip duration in seconds. Use 5 for the first request. Supported
            durations depend on the model.
          example: 5
        aspect_ratio:
          type: string
          description: Video output ratio.
          enum:
            - '16:9'
            - '9:16'
            - '1:1'
        generate_audio:
          type: boolean
          description: Generated audio for models that support it.
          default: false
        multi_prompt:
          type: array
          items:
            type: object
            properties:
              prompt:
                type: string
                description: Directions for this shot.
              duration:
                type: integer
                description: Shot length in seconds.
                minimum: 3
                maximum: 15
            required:
              - prompt
              - duration
            additionalProperties: false
          description: >-
            Kling 3 multi-shot directions. The shot durations determine the
            total duration. Use a single prompt first.
        negative_prompt:
          type: string
          description: Optional undesired visual characteristics.
        elements:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              asset_id:
                type: string
                format: uuid
              frontal_image_id:
                type: string
                format: uuid
              frontal_image_url:
                type: string
                format: uri
              reference_image_ids:
                type: array
                items:
                  type: string
                  format: uuid
              reference_image_urls:
                type: array
                items:
                  type: string
                  format: uri
          description: >-
            Kling 3 subject references. Provide an asset or direct image
            references for each element.
        avatar_text:
          type: string
          description: Additional avatar directions for supported video models.
        outfit_text:
          type: string
          description: Additional outfit directions for supported video models.
      required:
        - model
        - prompt
      additionalProperties: false
    JobResult:
      type: object
      nullable: true
      required:
        - image_id
        - url
        - width
        - height
      properties:
        image_id:
          type: string
          format: uuid
          description: >-
            Generated image or video ID. It equals the job ID. Completed image
            results can be used as a source for another image operation; video
            results cannot.
        url:
          type: string
          format: uri
          description: Completed media URL.
        width:
          type: integer
          nullable: true
        height:
          type: integer
          nullable: true
    JobError:
      type: object
      nullable: true
      required:
        - code
      properties:
        code:
          type: string
          description: >-
            Safe failure classification. Handle unknown or new values with a
            general failure message.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Create an API key in Studio → account menu → API Keys. Keep it on your
        server.

````