ai& Videos API

openapi: 3.2.0
info:
  title: ai& Videos API
  version: 1.0.0
  description: Unified spec covering inference, files, and other public surfaces. Drop-in compatible with OpenAI and Anthropic SDKs.
servers:
- url: https://api.aiand.com
  description: ai& API
security:
- bearerAuth: []
tags:
- name: Videos
paths:
  /v1/videos/models:
    get:
      operationId: listVideoModels
      tags:
      - Videos
      summary: List available video models
      description: 'Returns the video models you can generate with. Authentication is optional: authenticated callers see prices in their org''s billing currency, anonymous callers see USD. A credential that is present but invalid is rejected, never treated as anonymous. A model without a price in that currency is not returned, because it cannot be submitted.'
      security:
      - {}
      - bearerAuth: []
      responses:
        '200':
          description: The available models
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoModelList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/videos:
    post:
      operationId: createVideo
      tags:
      - Videos
      summary: Create a video generation job
      description: Submits an asynchronous generation job. The person creating the job must have agreed to the current Video Service Terms in the console playground; otherwise the request returns 403 `agreement_required`. The job is created in `moderating` status while input moderation runs; allowed jobs proceed through `translating` to `queued` and render, blocked jobs end `failed` with error code `moderation_blocked`, and a moderation outage fails the job closed with `moderation_unavailable`. Poll the returned job until its status is `completed`, then download the MP4 from `/content`.
      requestBody:
        description: The generation request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVideoJobRequest'
      responses:
        '200':
          description: The created job in `moderating` status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoJobObject'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    get:
      operationId: listVideos
      tags:
      - Videos
      summary: List video jobs
      description: Returns jobs in reverse-chronological order (newest first).
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        description: Page size
      - name: after
        in: query
        required: false
        schema:
          type: string
        description: 'Pagination cursor: a job id; returns jobs created before it'
      - name: mine
        in: query
        required: false
        schema:
          type: boolean
          default: false
        description: '`true` returns only jobs created by the caller (the API key''s owner); otherwise every job in the organization'
      responses:
        '200':
          description: Paginated list of video jobs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoJobList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v1/videos/acceptance:
    get:
      operationId: getVideoAcceptance
      tags:
      - Videos
      summary: Check Video Service Terms agreement
      description: Returns whether this person, in this organization, has agreed to the current Video Service Terms. Works with a console login or an API key.
      responses:
        '200':
          description: Current terms version and whether this person has agreed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoAcceptanceObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: postVideoAcceptance
      tags:
      - Videos
      summary: Agree to the Video Service Terms
      description: Records that this person agreed to the current Video Service Terms for this organization. Console login only — an API key is refused. A stale `version` is refused and writes nothing. Repeating the request is a success and does not write a second row.
      requestBody:
        description: The terms version being agreed to
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoAcceptanceRequest'
      responses:
        '200':
          description: Agreement recorded for the current version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoAcceptanceObject'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v1/videos/{id}:
    get:
      operationId: getVideo
      tags:
      - Videos
      summary: Retrieve a video job
      description: Returns job metadata. Jobs advance in the background; poll this endpoint until the status is `completed`, then download the MP4 from `/content`.
      responses:
        '200':
          description: The job's metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoJobObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
    delete:
      operationId: deleteVideo
      tags:
      - Videos
      summary: Delete a video job
      description: 'Permanently deletes a finished job: the generated video and the job record, including its prompt, are removed immediately. This cannot be undone. Jobs are deleted automatically 30 days after they finish, so calling this is only necessary to delete sooner. A job that is still running must finish before it can be deleted. The moderation record of the submission is retained for the full 30 days independently of this call.'
      responses:
        '200':
          description: Video deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoJobDeleted'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: No such video job in this organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The job is still running, or cannot be deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
  /v1/videos/{id}/content:
    get:
      operationId: getVideoContent
      tags:
      - Videos
      summary: Download the rendered video
      description: Streams the MP4 for a `completed` job.
      responses:
        '200':
          description: The MP4 bytes
          content:
            video/mp4:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
  /v1/videos/{id}/thumbnail:
    get:
      operationId: getVideoThumbnail
      tags:
      - Videos
      summary: Download the video's thumbnail
      description: 'Returns a JPEG still, 480 pixels wide, taken from near the start of a `completed` job. Check the job''s `thumbnail` field first: a job can complete without one.'
      responses:
        '200':
          description: The JPEG bytes
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
components:
  headers:
    x-ratelimit-remaining-global-requests:
      description: requests per minute still available for all models combined.
      schema:
        type: integer
    x-ratelimit-remaining-global-concurrency:
      description: in-flight requests still available for all models combined.
      schema:
        type: integer
    x-ratelimit-remaining-requests:
      description: requests per minute still available for this model.
      schema:
        type: integer
    x-ratelimit-remaining-tokens:
      description: input tokens per minute still available for this model.
      schema:
        type: integer
    x-ratelimit-limit-output-tokens:
      description: Cap on output tokens per minute for this model. Omitted when your tier has no such cap; a value of 0 on the requests or concurrency header means the model is closed to your tier.
      schema:
        type: integer
    x-ratelimit-reset-requests:
      description: Time until the requests per minute bucket for this model is full again, as a Go duration such as `45s` or `6m0s`. Not the same as Retry-After, which is the wait until one more request fits.
      schema:
        type: string
    x-ratelimit-limit-global-concurrency:
      description: Cap on in-flight requests for all models combined. Omitted when your tier has no such cap; a value of 0 on the requests or concurrency header means the model is closed to your tier.
      schema:
        type: integer
    x-ratelimit-reset-global-requests:
      description: Time until the requests per minute bucket for all models combined is full again, as a Go duration such as `45s` or `6m0s`. Not the same as Retry-After, which is the wait until one more request fits.
      schema:
        type: string
    x-ratelimit-limit-global-requests:
      description: Cap on requests per minute for all models combined. Omitted when your tier has no such cap; a value of 0 on the requests or concurrency header means the model is closed to your tier.
      schema:
        type: integer
    x-ratelimit-limit-tokens:
      description: Cap on input tokens per minute for this model. Omitted when your tier has no such cap; a value of 0 on the requests or concurrency header means the model is closed to your tier.
      schema:
        type: integer
    Retry-After:
      description: Seconds before retrying. Sent on authentication throttles and time-based model-bucket rejects; a concurrency reject clears when in-flight requests finish, not with time.
      schema:
        type: integer
    x-ratelimit-limit-requests:
      description: Cap on requests per minute for this model. Omitted when your tier has no such cap; a value of 0 on the requests or concurrency header means the model is closed to your tier.
      schema:
        type: integer
    x-ratelimit-limit-concurrency:
      description: Cap on in-flight requests for this model. Omitted when your tier has no such cap; a value of 0 on the requests or concurrency header means the model is closed to your tier.
      schema:
        type: integer
    x-ratelimit-remaining-concurrency:
      description: in-flight requests still available for this model.
      schema:
        type: integer
    x-ratelimit-remaining-output-tokens:
      description: output tokens per minute still available for this model.
      schema:
        type: integer
    X-RateLimit-Policy:
      description: The model-admission bucket that rejected the request. Absent on authentication throttles.
      schema:
        type: string
        enum:
        - rpm
        - input_tpm
        - output_tpm
        - concurrency
        - global_rpm
        - global_concurrency
    X-RateLimit-Limit:
      description: Deprecated compatibility alias for the limit of the RPM bucket with fewer remaining requests. Use the explicit per-model and global request headers instead.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Deprecated compatibility alias for the RPM bucket with fewer remaining requests. Use the explicit per-model and global request headers instead.
      schema:
        type: integer
    x-ratelimit-reset-tokens:
      description: Time until the input tokens per minute bucket for this model is full again, as a Go duration such as `45s` or `6m0s`. Not the same as Retry-After, which is the wait until one more request fits.
      schema:
        type: string
    x-ratelimit-reset-output-tokens:
      description: Time until the output tokens per minute bucket for this model is full again, as a Go duration such as `45s` or `6m0s`. Not the same as Retry-After, which is the wait until one more request fits.
      schema:
        type: string
  schemas:
    VideoModelPrice:
      type: object
      properties:
        resolution:
          type: string
          enum:
          - 768p
        per_second:
          type: string
          description: Decimal string; price for one second of output
        currency:
          type: string
          enum:
          - usd
          - jpy
      required:
      - resolution
      - per_second
      - currency
    VideoAcceptanceRequest:
      type: object
      properties:
        version:
          type: string
          description: The terms version the caller is agreeing to
      required:
      - version
      additionalProperties: false
    VideoModelObject:
      type: object
      properties:
        id:
          type: string
          description: Model identifier to pass as `model` when creating a job
        object:
          type: string
          const: video_model
        name:
          type: string
          description: Display name of the model
        description:
          type:
          - string
          - 'null'
        pricing:
          type: array
          items:
            $ref: '#/components/schemas/VideoModelPrice'
          description: Priced in the caller's billing currency, one entry per output resolution
      required:
      - id
      - object
      - name
      - description
      - pricing
    VideoJobError:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
      - code
      - message
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
            param:
              type: string
            code:
              type: string
          required:
          - message
          - type
      required:
      - error
    VideoJobDeleted:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          const: video
        deleted:
          type: boolean
          description: Always true on a successful delete
      required:
      - id
      - object
      - deleted
    VideoAcceptanceObject:
      type: object
      properties:
        object:
          type: string
          const: video_acceptance
        version:
          type: string
          description: The current Video Service Terms version
        accepted:
          type: boolean
          description: Whether this person, in this organization, has agreed to `version`
      required:
      - object
      - version
      - accepted
    CreateVideoJobRequest:
      anyOf:
      - type: object
        properties:
          model:
            type: string
            description: Video model to generate with
          prompt:
            type: string
            minLength: 1
            maxLength: 7000
            description: Text description of the video to generate
          seconds:
            type: integer
            minimum: 4
            maximum: 30
            description: Clip duration in seconds, 4-30. 16-30 seconds is experimental; quality may vary.
          aspect_ratio:
            type: string
            enum:
            - Auto
            - '21:9'
            - '16:9'
            - '4:3'
            - '1:1'
            - '3:4'
            - '9:16'
            description: Required output aspect ratio
          image_reference:
            type: array
            items:
              type: object
              properties:
                file_id:
                  type: string
                  minLength: 1
                  description: Id of a file uploaded with purpose `vision`
                role:
                  type: string
                  enum:
                  - first_frame
                  - last_frame
                  description: 'Where the image sits: the first or last frame'
              required:
              - file_id
              - role
              additionalProperties: false
            minItems: 1
            maxItems: 2
            description: One or two images with unique first_frame/last_frame roles.
        required:
        - model
        - prompt
        - seconds
        - aspect_ratio
        additionalProperties: false
      - type: object
        properties:
          model:
            type: string
            description: Video model to generate with
          prompt:
            type: string
            minLength: 1
            maxLength: 7000
            description: Text description of the video to generate
          seconds:
            type: integer
            minimum: 4
            maximum: 30
            description: Clip duration in seconds, 4-30. 16-30 seconds is experimental; quality may vary.
          aspect_ratio:
            type: string
            enum:
            - Auto
            - '21:9'
            - '16:9'
            - '4:3'
            - '1:1'
            - '3:4'
            - '9:16'
            description: Required output aspect ratio
          references:
            type: object
            properties:
              images:
                type: array
                items:
                  type: object
                  properties:
                    file_id:
                      type: string
                      minLength: 1
                  required:
                  - file_id
                  additionalProperties: false
                minItems: 1
                maxItems: 9
                description: Up to 9 images (purpose `vision`).
              videos:
                type: array
                items:
                  type: object
                  properties:
                    file_id:
                      type: string
                      minLength: 1
                  required:
                  - file_id
                  additionalProperties: false
                minItems: 1
                maxItems: 3
                description: Up to 3 video clips (purpose `video`).
              audio:
                type: array
                items:
                  type: object
                  properties:
                    file_id:
                      type: string
                      minLength: 1
                  required:
                  - file_id
                  additionalProperties: false
                minItems: 1
                maxItems: 3
                description: Up to 3 audio clips (purpose `audio`).
            additionalProperties: false
            description: Reference media to condition on. Up to 12 files in total. Cannot be combined with image_reference.
        required:
        - model
        - prompt
        - seconds
        - aspect_ratio
        - references
        additionalProperties: false
    VideoJobList:
      type: object
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/VideoJobObject'
        has_more:
          type: boolean
        first_id:
          type:
          - string
          - 'null'
        last_id:
          type:
          - string
          - 'null'
      required:
      - object
      - data
      - has_more
      - first_id
      - last_id
    VideoJobObject:
      type: object
      properties:
        id:
          type: string
          description: Stable job id with `video_` prefix
        object:
          type: string
          const: video
        model:
          type: string
        prompt:
          type: string
        seconds:
          type: integer
        status:
          type: string
          enum:
          - moderating
          - translating
          - queued
          - in_progress
          - completed
          - failed
          - canceled
          description: Jobs start as `moderating` while input moderation runs, then progress through `translating` (prompt translation), `queued`, and `in_progress`. Treat any unrecognized status as still running — new intermediate stages may be added.
        error:
          oneOf:
          - $ref: '#/components/schemas/VideoJobError'
          - type: 'null'
          description: Populated only when status is `failed`. Code `moderation_blocked` means the input was refused by content moderation; `moderation_unavailable` means the moderation system was down; `translation_unavailable` means a Japanese prompt could not be translated. Unavailable jobs fail closed — resubmit later.
        cost:
          type:
          - string
          - 'null'
          description: Exact quoted charge as a decimal string, fixed when the job is accepted
        currency:
          type:
          - string
          - 'null'
          enum:
          - usd
          - jpy
          - null
          description: Currency of the quoted `cost`
        created_at:
          type: integer
          description: Unix timestamp
        completed_at:
          type:
          - integer
          - 'null'
          description: Unix timestamp
        thumbnail:
          type: boolean
          description: '`true` when the job has a thumbnail to download from `GET /v1/videos/{video_id}/thumbnail`'
      required:
      - id
      - object
      - model
      - prompt
      - seconds
      - status
      - error
      - cost
      - currency
      - created_at
      - completed_at
      - thumbnail
    VideoModelList:
      type: object
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/VideoModelObject'
      required:
      - object
      - data
  responses:
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServiceUnavailable:
      description: Service Unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Rate Limited
      headers:
        x-ratelimit-limit-requests:
          $ref: '#/components/headers/x-ratelimit-limit-requests'
        x-ratelimit-remaining-requests:
          $ref: '#/components/headers/x-ratelimit-remaining-requests'
        x-ratelimit-reset-requests:
          $ref: '#/components/headers/x-ratelimit-reset-requests'
        x-ratelimit-limit-tokens:
          $ref: '#/components/headers/x-ratelimit-limit-tokens'
        x-ratelimit-remaining-tokens:
          $ref: '#/components/headers/x-ratelimit-remaining-tokens'
        x-ratelimit-reset-tokens:
          $ref: '#/components/headers/x-ratelimit-reset-tokens'
        x-ratelimit-limit-output-tokens:
          $ref: '#/components/headers/x-ratelimit-limit-output-tokens'
        x-ratelimit-remaining-output-tokens:
          $ref: '#/components/headers/x-ratelimit-remaining-output-tokens'
        x-ratelimit-reset-output-tokens:
          $ref: '#/components/headers/x-ratelimit-reset-output-tokens'
        x-ratelimit-limit-concurrency:
          $ref: '#/components/headers/x-ratelimit-limit-concurrency'
        x-ratelimit-remaining-concurrency:
          $ref: '#/components/headers/x-ratelimit-remaining-concurrency'
        x-ratelimit-limit-global-requests:
          $ref: '#/components/headers/x-ratelimit-limit-global-requests'
        x-ratelimit-remaining-global-requests:
          $ref: '#/components/headers/x-ratelimit-remaining-global-requests'
        x-ratelimit-reset-global-requests:
          $ref: '#/components/headers/x-ratelimit-reset-global-requests'
        x-ratelimit-limit-global-concurrency:
          $ref: '#/components/headers/x-ratelimit-limit-global-concurrency'
        x-ratelimit-remaining-global-concurrency:
          $ref: '#/components/headers/x-ratelimit-remaining-global-concurrency'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Policy:
          $ref: '#/components/headers/X-RateLimit-Policy'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'Authorization: Bearer <API_KEY>'