# Generated by scripts/build-api-docs.sh from api/openapi.yaml. Do not edit.
openapi: 3.0.3
info:
  title: voao pro public API
  version: v1
  description: >-
    Generate with voao pro's models from your own systems: list models, price a request, submit a
    job, be told when it ends and fetch the result. Authenticate with an API key (Authorization:
    Bearer vk_...).
servers:
  - url: /
security:
  - bearerAuth: []
tags:
  - name: public
    description: The /v1 generation API
paths:
  /v1/models:
    get:
      operationId: publicListModels
      tags:
        - public
      security:
        - bearerAuth: []
      summary: The models the org's plan offers (scope models:read)
      description: >
        Models above the plan are listed with locked set and cannot be used. input_schema describes
        the settings a job of the model takes.
      responses:
        "200":
          description: The models
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelList"
        default:
          $ref: "#/components/responses/Error"
  /v1/tools:
    get:
      operationId: publicListTools
      tags:
        - public
      security:
        - bearerAuth: []
      summary: The tools the org's plan offers (scope models:read)
      responses:
        "200":
          description: The tools
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ToolList"
        default:
          $ref: "#/components/responses/Error"
  /v1/price:
    post:
      operationId: publicPreviewPrice
      tags:
        - public
      security:
        - bearerAuth: []
      summary: The price of a job before it is submitted (scope models:read or jobs:write)
      description: >
        Runs the checks and the pricing a submission runs and reserves nothing, so the number is the
        number a job of the same request would reserve.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PublicJobRequest"
      responses:
        "200":
          description: The price
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PricePreview"
        default:
          $ref: "#/components/responses/Error"
  /v1/jobs:
    post:
      operationId: publicCreateJob
      tags:
        - public
      security:
        - bearerAuth: []
      summary: Submit a generation job (scope jobs:write)
      description: >
        Prices the job, reserves its credits and queues it in one step. The Idempotency-Key header
        is required (up to 200 characters); the same key with the same request returns the job
        already made, the same key with a different request is idempotency_key_reused (409).
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: Chosen by the client. A missing key is refused with idempotency_key_required (422).
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PublicJobRequest"
      responses:
        "201":
          description: The job
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicJob"
        default:
          $ref: "#/components/responses/Error"
    get:
      operationId: publicListJobs
      tags:
        - public
      security:
        - bearerAuth: []
      summary: The jobs made through API keys in the key's workspace, newest first (scope jobs:read)
      parameters:
        - name: cursor
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
        - name: status
          in: query
          schema:
            $ref: "#/components/schemas/JobStatus"
      responses:
        "200":
          description: A page of jobs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicJobPage"
        default:
          $ref: "#/components/responses/Error"
  /v1/jobs/{jobId}:
    get:
      operationId: publicGetJob
      tags:
        - public
      security:
        - bearerAuth: []
      summary: One job of the key's workspace (scope jobs:read)
      parameters:
        - $ref: "#/components/parameters/JobId"
      responses:
        "200":
          description: The job
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicJob"
        default:
          $ref: "#/components/responses/Error"
  /v1/jobs/{jobId}/cancel:
    post:
      operationId: publicCancelJob
      tags:
        - public
      security:
        - bearerAuth: []
      summary: Cancel a job made through an API key (scope jobs:write)
      description: >
        A queued job is cancelled at once and its credits return; one already at the provider is
        left to finish. A finished job cannot be cancelled (job_not_cancellable).
      parameters:
        - $ref: "#/components/parameters/JobId"
      responses:
        "200":
          description: The job after the request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicJob"
        default:
          $ref: "#/components/responses/Error"
  /v1/assets/uploads:
    post:
      operationId: publicStartUpload
      tags:
        - public
      security:
        - bearerAuth: []
      summary: Start uploading a file to use as a setting of a job (scope assets:write)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StartUploadRequest"
      responses:
        "201":
          description: The upload to send
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadPlan"
        default:
          $ref: "#/components/responses/Error"
  /v1/assets/{assetId}/upload/parts:
    post:
      operationId: publicSignUploadParts
      tags:
        - public
      security:
        - bearerAuth: []
      summary: Links for sending the named parts (scope assets:write)
      parameters:
        - $ref: "#/components/parameters/AssetId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SignPartsRequest"
      responses:
        "200":
          description: The links
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PartLinks"
        default:
          $ref: "#/components/responses/Error"
  /v1/assets/{assetId}/complete:
    post:
      operationId: publicCompleteUpload
      tags:
        - public
      security:
        - bearerAuth: []
      summary: Confirm an upload (scope assets:write)
      parameters:
        - $ref: "#/components/parameters/AssetId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CompleteUploadRequest"
      responses:
        "200":
          description: The asset
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Asset"
        default:
          $ref: "#/components/responses/Error"
  /v1/assets/{assetId}:
    get:
      operationId: publicGetAsset
      tags:
        - public
      security:
        - bearerAuth: []
      summary: One asset of the key's workspace (scope assets:read)
      parameters:
        - $ref: "#/components/parameters/AssetId"
      responses:
        "200":
          description: The asset
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Asset"
        default:
          $ref: "#/components/responses/Error"
  /v1/assets/{assetId}/download:
    get:
      operationId: publicGetAssetDownload
      tags:
        - public
      security:
        - bearerAuth: []
      summary: A signed, expiring link to the delivered file (scope assets:read)
      description: >
        A generated picture or video is delivered with the org's copyright notice and a mark id in
        its metadata, and with a visible watermark unless the plan removes it. A video's marked copy
        is made first: until it is ready the answer is 202; ask again.
      parameters:
        - $ref: "#/components/parameters/AssetId"
      responses:
        "200":
          description: The link
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DownloadLink"
        "202":
          description: The marked copy is being prepared; ask again shortly
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DownloadPreparing"
        default:
          $ref: "#/components/responses/Error"
  /v1/usage:
    get:
      operationId: publicGetUsage
      tags:
        - public
      security:
        - bearerAuth: []
      summary: Usage of API keys by day (scope usage:read)
      description: Jobs made through API keys in the key's workspace, per day (UTC) and key, for up to a year.
      parameters:
        - $ref: "#/components/parameters/UsageFrom"
        - $ref: "#/components/parameters/UsageTo"
      responses:
        "200":
          description: The usage
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiUsage"
        default:
          $ref: "#/components/responses/Error"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key, sent as Authorization Bearer. Only the /v1 operations accept it.
  parameters:
    AssetId:
      name: assetId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    JobId:
      name: jobId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    UsageFrom:
      name: from
      in: query
      required: false
      description: First day (UTC, YYYY-MM-DD); defaults to 30 days before to
      schema:
        type: string
        format: date
    UsageTo:
      name: to
      in: query
      required: false
      description: Last day (UTC, YYYY-MM-DD, included); defaults to today. The period is at most one year.
      schema:
        type: string
        format: date
  responses:
    Error:
      description: Error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  schemas:
    ApiUsage:
      type: object
      required:
        - from
        - to
        - rows
        - totals
      properties:
        from:
          type: string
          format: date
        to:
          type: string
          format: date
        rows:
          type: array
          items:
            $ref: "#/components/schemas/ApiUsageRow"
        totals:
          type: object
          required:
            - jobs
            - succeeded
            - failed
            - blocked
            - cancelled
            - credits
          properties:
            jobs:
              type: integer
              format: int64
            succeeded:
              type: integer
              format: int64
            failed:
              type: integer
              format: int64
            blocked:
              type: integer
              format: int64
            cancelled:
              type: integer
              format: int64
            credits:
              type: integer
              format: int64
    ApiUsageRow:
      type: object
      required:
        - day
        - api_key_id
        - api_key_name
        - workspace_id
        - jobs
        - succeeded
        - failed
        - blocked
        - cancelled
        - credits
      properties:
        day:
          type: string
          format: date
        api_key_id:
          type: string
          format: uuid
        api_key_name:
          type: string
        workspace_id:
          type: string
          format: uuid
        jobs:
          type: integer
          format: int64
        succeeded:
          type: integer
          format: int64
        failed:
          type: integer
          format: int64
        blocked:
          type: integer
          format: int64
        cancelled:
          type: integer
          format: int64
        credits:
          type: integer
          format: int64
          description: Credits settled by the succeeded jobs
    Asset:
      type: object
      required:
        - id
        - workspace_id
        - kind
        - content_type
        - size_bytes
        - name
        - source
        - created_by
        - created_by_name
        - created_at
      properties:
        id:
          type: string
          format: uuid
        workspace_id:
          type: string
          format: uuid
        kind:
          $ref: "#/components/schemas/AssetKind"
        content_type:
          type: string
        size_bytes:
          type: integer
          format: int64
        duration_seconds:
          type: number
          format: double
          description: The length of a video, or of a WAV or M4A recording, when it is known
        width:
          type: integer
          description: The width of a picture in pixels, when it is known
        height:
          type: integer
          description: The height of a picture in pixels, when it is known
        name:
          type: string
        source:
          type: string
          enum:
            - upload
            - generated
        job_id:
          type: string
          format: uuid
        created_by:
          type: string
          format: uuid
        created_by_name:
          type: string
        created_at:
          type: string
          format: date-time
        url:
          type: string
          description: >-
            A link to view or play the file; works until url_expires_at. Re-request the asset for a
            fresh one.
        url_expires_at:
          type: string
          format: date-time
        project_ids:
          type: array
          description: The projects this asset is in
          items:
            type: string
            format: uuid
    AssetKind:
      type: string
      enum:
        - image
        - video
        - audio
        - subtitle
        - model
        - document
    CompleteUploadRequest:
      type: object
      required:
        - parts
      properties:
        parts:
          type: array
          items:
            type: object
            required:
              - number
              - etag
            properties:
              number:
                type: integer
                minimum: 1
              etag:
                type: string
    DownloadLink:
      type: object
      required:
        - url
        - expires_at
      properties:
        url:
          type: string
        expires_at:
          type: string
          format: date-time
        marked:
          type: boolean
          description: True when the file carries a visible watermark
    DownloadPreparing:
      type: object
      required:
        - state
      properties:
        state:
          type: string
          enum:
            - preparing
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Stable machine-readable code, e.g. seat_limit_reached
            message:
              type: string
            details:
              type: object
              additionalProperties: true
    JobStatus:
      type: string
      enum:
        - queued
        - submitted
        - running
        - finalizing
        - succeeded
        - failed
        - blocked
        - cancelled
      description: >
        finalizing means the provider has finished and the result is being saved; credits are
        settled only after.
    ModelInfo:
      type: object
      required:
        - key
        - name
        - kind
        - beta
        - locked
        - input_schema
        - ui_schema
      properties:
        key:
          type: string
        name:
          type: string
        kind:
          $ref: "#/components/schemas/ModelKind"
        beta:
          type: boolean
        locked:
          type: boolean
          description: The org's plan does not include this model
        tab:
          type: string
          enum:
            - asset
            - scene
          description: The tab of the 3D Studio the model is in (only models of kind 3d have one)
        result:
          type: string
          enum:
            - file
            - voice
            - data
          description: >-
            What a job of the model makes - a file (the default), a saved voice or data (a text
            model); only a file can be passed on in a canvas
        input_schema:
          type: object
          additionalProperties: true
        ui_schema:
          type: object
          additionalProperties: true
    ModelKind:
      type: string
      enum:
        - image
        - video
        - audio
        - text
        - 3d
    ModelList:
      type: object
      required:
        - models
      properties:
        models:
          type: array
          items:
            $ref: "#/components/schemas/ModelInfo"
    PartLinks:
      type: object
      required:
        - parts
      properties:
        parts:
          type: array
          items:
            type: object
            required:
              - number
              - url
            properties:
              number:
                type: integer
              url:
                type: string
    PricePreview:
      type: object
      required:
        - price
      properties:
        price:
          type: integer
          format: int64
    PublicJob:
      type: object
      required:
        - id
        - model
        - status
        - price
        - input
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
        model:
          type: string
        status:
          $ref: "#/components/schemas/JobStatus"
        price:
          type: integer
          format: int64
          description: Credits reserved, and settled when the job succeeds
        input:
          type: object
          additionalProperties: true
        result_asset_ids:
          type: array
          description: The files a succeeded job made, as asset ids; fetch them with the assets endpoints
          items:
            type: string
            format: uuid
        error_code:
          type: string
        error_message:
          type: string
        queue_position:
          type: integer
          description: Place in the queue (1 is next); only while queued
        created_at:
          type: string
          format: date-time
        submitted_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    PublicJobPage:
      type: object
      required:
        - jobs
      properties:
        jobs:
          type: array
          items:
            $ref: "#/components/schemas/PublicJob"
        next_cursor:
          type: string
    PublicJobRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
          example: fake-image
        input:
          type: object
          additionalProperties: true
          description: The settings the model takes (see input_schema in the model list)
    SignPartsRequest:
      type: object
      required:
        - parts
      properties:
        parts:
          type: array
          items:
            type: integer
            minimum: 1
    StartUploadRequest:
      type: object
      required:
        - name
        - content_type
        - size_bytes
      properties:
        name:
          type: string
        content_type:
          type: string
          example: image/png
        size_bytes:
          type: integer
          format: int64
    ToolInfo:
      type: object
      required:
        - key
        - name
        - kind
        - group
        - order
        - beta
        - locked
        - input_schema
        - ui_schema
      properties:
        key:
          type: string
        name:
          type: string
        kind:
          $ref: "#/components/schemas/ModelKind"
        group:
          type: string
          enum:
            - image
            - video
            - audio
            - analysis
            - subtitles
        order:
          type: integer
        beta:
          type: boolean
        locked:
          type: boolean
          description: The org's plan does not include this tool
        result:
          type: string
          enum:
            - file
            - data
          description: Whether a run makes a new file or only data shown on the page
        input_schema:
          type: object
          additionalProperties: true
        ui_schema:
          type: object
          additionalProperties: true
    ToolList:
      type: object
      required:
        - tools
      properties:
        tools:
          type: array
          items:
            $ref: "#/components/schemas/ToolInfo"
    UploadPlan:
      type: object
      required:
        - asset_id
        - part_size
        - part_count
      properties:
        asset_id:
          type: string
          format: uuid
        part_size:
          type: integer
          format: int64
          description: Bytes per part except the last
        part_count:
          type: integer