openapi: 3.1.0
info:
  title: Volcano Engine Ark API (Doubao)
  description: >-
    Volcano Engine Ark serves ByteDance's Doubao foundation models with an
    OpenAI-compatible API surface. Provides chat completions, embeddings,
    image generation (Seedream), video generation (Seedance), and batch
    operations. Endpoints derived from public Volcano Engine documentation at
    https://www.volcengine.com/docs/82379 — best-effort, not exhaustive.
    Authenticates with a Bearer API key minted in the Ark console.
  version: "3"
  contact:
    name: Volcano Engine
    url: https://www.volcengine.com
  license:
    name: Proprietary
servers:
  - url: https://ark.cn-beijing.volces.com/api/v3
    description: Volcano Engine Ark - Beijing region
security:
  - BearerAuth: []
tags:
  - name: Chat
  - name: Embeddings
  - name: Images
  - name: Videos
  - name: Batch
paths:
  /chat/completions:
    post:
      tags: [Chat]
      summary: Create a chat completion
      operationId: createChatCompletion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
  /embeddings:
    post:
      tags: [Embeddings]
      summary: Create embeddings
      operationId: createEmbeddings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [model, input]
              properties:
                model: { type: string }
                input:
                  oneOf:
                    - type: string
                    - type: array
                      items: { type: string }
                encoding_format: { type: string, enum: [float, base64] }
      responses:
        '200':
          description: OK
  /images/generations:
    post:
      tags: [Images]
      summary: Generate images (Seedream)
      operationId: createImage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [model, prompt]
              properties:
                model: { type: string }
                prompt: { type: string }
                response_format: { type: string, enum: [url, b64_json] }
                size: { type: string }
                n: { type: integer, default: 1 }
      responses:
        '200':
          description: OK
  /contents/generations/tasks:
    post:
      tags: [Videos]
      summary: Create a video generation task (Seedance)
      operationId: createVideoTask
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [model, content]
              properties:
                model: { type: string }
                content:
                  type: array
                  items:
                    type: object
                    properties:
                      type: { type: string }
                      text: { type: string }
                      image_url:
                        type: object
                        properties:
                          url: { type: string }
      responses:
        '200':
          description: OK
  /contents/generations/tasks/{task_id}:
    get:
      tags: [Videos]
      summary: Retrieve video generation task
      operationId: getVideoTask
      parameters:
        - in: path
          name: task_id
          required: true
          schema: { type: string }
      responses:
        '200':
          description: OK
    delete:
      tags: [Videos]
      summary: Cancel video generation task
      operationId: deleteVideoTask
      parameters:
        - in: path
          name: task_id
          required: true
          schema: { type: string }
      responses:
        '200':
          description: OK
  /batch/chat/completions:
    post:
      tags: [Batch]
      summary: Create a batch chat completion job
      operationId: createBatchChatCompletion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: OK
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Ark API Key
  schemas:
    ChatCompletionRequest:
      type: object
      required: [model, messages]
      properties:
        model: { type: string, example: doubao-seed-1-6 }
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage'
        temperature: { type: number, default: 1 }
        top_p: { type: number, default: 1 }
        max_tokens: { type: integer }
        stream: { type: boolean, default: false }
        tools:
          type: array
          items:
            type: object
            additionalProperties: true
    ChatMessage:
      type: object
      required: [role]
      properties:
        role: { type: string, enum: [system, user, assistant, tool] }
        content:
          oneOf:
            - type: string
            - type: array
              items:
                type: object
                properties:
                  type: { type: string }
                  text: { type: string }
                  image_url:
                    type: object
                    properties:
                      url: { type: string }
        name: { type: string }
        tool_call_id: { type: string }
    ChatCompletionResponse:
      type: object
      properties:
        id: { type: string }
        object: { type: string }
        created: { type: integer }
        model: { type: string }
        choices:
          type: array
          items:
            type: object
            properties:
              index: { type: integer }
              message:
                $ref: '#/components/schemas/ChatMessage'
              finish_reason: { type: string }
        usage:
          type: object
          properties:
            prompt_tokens: { type: integer }
            completion_tokens: { type: integer }
            total_tokens: { type: integer }