> ## 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.

# Generate an image

> Create a fashion photo from a prompt and optional product references.

Describe the person and scene in `prompt` or `model_text`. Add product references with one of `outfit_image_ids`, `outfit_asset_ids`, or `outfit_image_urls`. Saved avatars, presets and poses go in `asset_ids`.

The default model is `nano-banana-2`, with `resolution: "standard"` and one output. Generate supports up to three garment references and up to eight outputs, subject to account limits.

A successful request returns HTTP `202` with a `jobs` array. Save each `id`, then [get the job](/api-reference/jobs/get) until it finishes. Read the completed media from `result.url` and its reusable ID from `result.id`. Use an [Idempotency-Key](/api-reference/errors) when submitting work that may be retried.

<Columns cols={2}>
  <Card title="Start from a prompt" href="/api-reference/generate/from-prompt">Describe a new fashion image.</Card>
  <Card title="Use your products" href="/api-reference/generate/product-photos">Add garment photos or saved assets.</Card>
  <Card title="Choose output settings" href="/api-reference/generate/settings">Set quality, proportions, and output count.</Card>
  <Card title="Run the quickstart" href="/api-reference/quickstart">Upload, generate, and retrieve a result with Node.js.</Card>
</Columns>


## OpenAPI

````yaml api-reference/openapi.json POST /v1/images/generate
openapi: 3.0.3
info:
  title: bitStudio public API
  version: 1.0.0
  description: >-
    Public v1 operations. Create work with a focused endpoint, then retrieve its
    job. Media IDs are opaque; API clients do not manage Studio versions. New
    response fields may be added; clients should ignore fields they do not
    recognize.
servers:
  - url: https://api.bitstudio.ai
    description: Production
security:
  - bearerAuth: []
paths:
  /v1/images/generate:
    post:
      summary: Generate an image
      operationId: generate
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 128
            pattern: ^[!-~]+$
          description: >-
            Use a unique key for each intended creation. Retry the same method,
            path and JSON with the same key to replay its response for 24 hours
            after completion. Conflicting requests and unfinished or uncertain
            outcomes return 409. An uncertain receipt is never automatically
            rerun.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicGenerateRequest'
            example:
              prompt: An adult fashion model in a white studio
              aspect_ratio: '3:4'
      responses:
        '202':
          description: Accepted; poll each job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Submission'
              example:
                jobs:
                  - id: 11111111-1111-4111-8111-111111111111
                    status: pending
                    task: generate
                    created_at: '2026-09-15T12:00:00Z'
                    result: null
                    error: null
                    credits_used: 2
        default:
          description: Request failed; inspect code and message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    PublicGenerateRequest:
      type: object
      additionalProperties: false
      properties:
        model:
          type: string
          default: nano-banana-2
          description: Model for this operation. Account and plan limits apply.
        resolution:
          type: string
          enum:
            - standard
            - high
          default: standard
          description: Output quality; dimensions depend on the model and aspect ratio.
        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.
        aspect_ratio:
          type: string
          description: >-
            Model-dependent output ratio. 3:4 is supported by nano-banana-2 and
            nano-banana-pro.
          example: '3:4'
        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_image_ids:
          type: array
          items:
            type: string
            description: Resource ID.
            format: uuid
          description: Garment references; choose one outfit source array per request.
          maxItems: 3
          minItems: 1
        outfit_image_urls:
          type: array
          items:
            type: string
            description: ''
            format: uri
          description: Garment references; choose one outfit source array per request.
          maxItems: 3
          minItems: 1
        outfit_asset_ids:
          type: array
          items:
            type: string
            description: Resource ID.
            format: uuid
          description: Garment references; choose one outfit source array per request.
          maxItems: 3
          minItems: 1
        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.
        style:
          type: string
          description: Optional style directions.
        style_id:
          type: string
          description: Optional saved style asset ID.
      allOf:
        - oneOf:
            - required:
                - outfit_image_ids
            - required:
                - outfit_asset_ids
            - required:
                - outfit_image_urls
            - not:
                anyOf:
                  - required:
                      - outfit_image_ids
                  - required:
                      - outfit_asset_ids
                  - required:
                      - outfit_image_urls
    Submission:
      type: object
      required:
        - jobs
      properties:
        jobs:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Job'
    Error:
      type: object
      required:
        - code
        - message
        - request_id
      properties:
        code:
          type: string
        message:
          type: string
        request_id:
          type: string
          format: uuid
        error:
          type: string
          description: Compatibility error description.
        cta:
          type: boolean
          description: Account action is required.
        next_action:
          type: string
    Job:
      type: object
      required:
        - id
        - status
        - task
        - created_at
        - result
        - error
        - credits_used
      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'
        credits_used:
          type: number
          minimum: 0
          description: >-
            Credits currently charged for this output, in display credits: 1
            means one Studio credit. Fractional amounts are preserved. A
            completed refund is reflected as 0 when polling. Creation and
            idempotency replay responses are snapshots; poll for the latest
            charge.
          example: 1.5
    JobResult:
      type: object
      nullable: true
      required:
        - image_id
        - url
        - width
        - height
        - id
        - type
      properties:
        image_id:
          type: string
          format: uuid
          description: Compatibility alias for id. Use id for new integrations.
        url:
          type: string
          format: uri
          description: Completed media URL.
        width:
          type: integer
          nullable: true
        height:
          type: integer
          nullable: true
        id:
          type: string
          format: uuid
          description: >-
            Opaque media ID. Pass an image result ID into the next image
            operation.
        type:
          type: string
          enum:
            - image
            - video
    JobError:
      type: object
      nullable: true
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: >-
            Safe failure classification. Handle unknown or new values with a
            general failure message.
        message:
          type: string
          description: Safe, readable failure description.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Create an API key in Studio → account menu → API Keys. Keep it on your
        server.

````