openapi: 3.0.3
info:
  title: Jina AI Embeddings API
  description: >-
    Generate high-quality multimodal embeddings for text, image, and code inputs
    using Jina AI's state-of-the-art embedding models. Supports synchronous
    embedding requests and batch jobs for large workloads.
  version: '1.0'
  contact:
    name: Jina AI
    url: https://jina.ai
servers:
  - url: https://api.jina.ai/v1
    description: Jina AI production API
security:
  - BearerAuth: []
tags:
  - name: Embeddings
    description: Synchronous embedding generation
  - name: Batch
    description: Asynchronous batch embedding jobs
paths:
  /embeddings:
    post:
      tags:
        - Embeddings
      summary: Create embeddings
      description: Generate vector embeddings for one or more text, image, or code inputs.
      operationId: createEmbeddings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmbeddingRequest'
      responses:
        '200':
          description: Embeddings successfully generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingResponse'
        '401':
          description: Unauthorized
        '429':
          description: Rate limit exceeded
  /batch/embeddings:
    post:
      tags:
        - Batch
      summary: Submit batch embedding job
      description: Submit a batch job to embed a large set of inputs asynchronously.
      operationId: submitBatchEmbeddings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchEmbeddingRequest'
      responses:
        '202':
          description: Batch job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchJob'
  /batch/{batch_id}:
    get:
      tags:
        - Batch
      summary: Get batch job status
      operationId: getBatchJob
      parameters:
        - name: batch_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Batch job status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchJob'
    delete:
      tags:
        - Batch
      summary: Cancel batch job
      operationId: cancelBatchJob
      parameters:
        - name: batch_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Batch job cancelled
  /batch/{batch_id}/output:
    get:
      tags:
        - Batch
      summary: Download batch job output
      operationId: getBatchOutput
      parameters:
        - name: batch_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Batch output stream
  /batch/{batch_id}/errors:
    get:
      tags:
        - Batch
      summary: Retrieve batch job errors
      operationId: getBatchErrors
      parameters:
        - name: batch_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Batch errors stream
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
  schemas:
    EmbeddingRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
          description: Embedding model identifier
          example: jina-embeddings-v4
          enum:
            - jina-embeddings-v5-text-small
            - jina-embeddings-v5-text-nano
            - jina-embeddings-v4
            - jina-embeddings-v3
            - jina-clip-v2
        input:
          type: array
          description: Inputs to embed (text strings or image references)
          items:
            type: string
        task:
          type: string
          description: Downstream task to optimize the embedding for
          enum:
            - retrieval.query
            - retrieval.passage
            - text-matching
            - classification
            - clustering
        dimensions:
          type: integer
          description: Optional truncation length for output vectors
        normalized:
          type: boolean
          description: Whether to L2-normalize the output vectors
        embedding_type:
          type: string
          enum: [float, base64, binary, ubinary]
    EmbeddingResponse:
      type: object
      properties:
        model:
          type: string
        object:
          type: string
          example: list
        usage:
          $ref: '#/components/schemas/Usage'
        data:
          type: array
          items:
            $ref: '#/components/schemas/EmbeddingObject'
    EmbeddingObject:
      type: object
      properties:
        object:
          type: string
          example: embedding
        index:
          type: integer
        embedding:
          type: array
          items:
            type: number
            format: float
    Usage:
      type: object
      properties:
        total_tokens:
          type: integer
        prompt_tokens:
          type: integer
    BatchEmbeddingRequest:
      type: object
      required:
        - model
        - input_file_id
      properties:
        model:
          type: string
        input_file_id:
          type: string
          description: Identifier of an uploaded input file
        endpoint:
          type: string
          example: /v1/embeddings
        completion_window:
          type: string
          example: 24h
    BatchJob:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: [validating, in_progress, completed, failed, cancelling, cancelled]
        created_at:
          type: integer
        endpoint:
          type: string
        request_counts:
          type: object
          properties:
            total:
              type: integer
            completed:
              type: integer
            failed:
              type: integer