{
  "openapi": "3.1.0",
  "info": {
    "title": "NexInfer Compatible API",
    "version": "2026-07-27",
    "description": "Public NexInfer API contract. Documented fields are preserved by NexInfer; actual support remains model dependent. Unknown model-provider fields are accepted for compatibility."
  },
  "servers": [{ "url": "https://api.nexinfer.com" }],
  "security": [{ "bearerAuth": [] }],
  "paths": {
    "/v1/models": {
      "get": {
        "operationId": "listModels",
        "summary": "List models visible to the current API key",
        "responses": {
          "200": { "description": "Model list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/v1/responses": {
      "post": {
        "operationId": "createResponse",
        "summary": "Create an OpenAI-compatible response",
        "description": "NexInfer production acceptance covers non-streaming JSON and streaming SSE.",
        "x-nexinfer-verified-modes": ["non-stream", "stream"],
        "requestBody": { "$ref": "#/components/requestBodies/ResponseRequest" },
        "responses": {
          "200": { "$ref": "#/components/responses/ResponseOrSSE" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/responses": {
      "post": {
        "operationId": "createResponseCompat",
        "summary": "Compatibility alias for /v1/responses",
        "description": "Compatibility alias verified for non-streaming JSON and streaming SSE.",
        "x-nexinfer-verified-modes": ["non-stream", "stream"],
        "requestBody": { "$ref": "#/components/requestBodies/ResponseRequest" },
        "responses": { "200": { "$ref": "#/components/responses/ResponseOrSSE" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      }
    },
    "/v1/chat/completions": {
      "post": {
        "operationId": "createChatCompletion",
        "summary": "Create an OpenAI-compatible chat completion",
        "requestBody": { "$ref": "#/components/requestBodies/ChatRequest" },
        "responses": { "200": { "$ref": "#/components/responses/ChatOrSSE" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }
      }
    },
    "/v1/messages": {
      "post": {
        "operationId": "createMessage",
        "summary": "Create an Anthropic-compatible message",
        "description": "Claude support is retained for forward compatibility but is not part of the current public 12-model catalog.",
        "x-nexinfer-availability": "coming-soon",
        "security": [{ "apiKeyAuth": [] }],
        "requestBody": { "$ref": "#/components/requestBodies/MessageRequest" },
        "responses": { "200": { "$ref": "#/components/responses/JsonOrSSE" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }
      }
    },
    "/v1/images/generations": {
      "post": {
        "operationId": "generateImages",
        "summary": "Generate images",
        "x-nexinfer-known-limitations": ["gpt-image-2 exact size and quality are not currently preserved", "gpt-image-2 and Seedream currently require n=1"],
        "x-nexinfer-model-notes": {
          "gpt-image-2": "Single-image generation; exact size and quality options, multiple images, and direct edits are not currently guaranteed.",
          "doubao-seedream-5-0-pro-260628": "Text-to-image and one or multiple reference images; image accepts a string or up to 10 strings."
        },
        "requestBody": { "$ref": "#/components/requestBodies/ImageGenerationRequest" },
        "responses": { "200": { "$ref": "#/components/responses/ImageOrSSE" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }
      }
    },
    "/v1/images/edits": {
      "post": {
        "operationId": "editImages",
        "summary": "Edit one or more images",
        "x-nexinfer-known-limitations": ["gpt-image-2 direct edits are not currently supported", "Seedream currently requires n=1"],
        "x-nexinfer-model-notes": {
          "doubao-seedream-5-0-pro-260628": "Accepts multipart reference-image uploads for Seedream editing; the current result contains one image."
        },
        "requestBody": { "$ref": "#/components/requestBodies/ImageEditRequest" },
        "responses": { "200": { "$ref": "#/components/responses/ImageOrSSE" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }
      }
    },
    "/v1/video/generations": {
      "post": {
        "operationId": "createVideoGeneration",
        "summary": "Create an asynchronous video generation task",
        "requestBody": { "$ref": "#/components/requestBodies/VideoRequest" },
        "responses": { "200": { "description": "Queued video task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoTask" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }
      }
    },
    "/v1/video/generations/{task_id}": {
      "get": {
        "operationId": "getVideoGeneration",
        "summary": "Get video task status",
        "parameters": [{ "$ref": "#/components/parameters/TaskId" }],
        "responses": { "200": { "description": "Current task status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoTask" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    },
    "/v1/videos/{task_id}/content": {
      "get": {
        "operationId": "downloadVideoContent",
        "summary": "Download completed video content",
        "parameters": [{ "$ref": "#/components/parameters/TaskId" }],
        "responses": { "200": { "description": "Video bytes", "content": { "video/mp4": { "schema": { "type": "string", "contentEncoding": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Task has not completed" } }
      }
    },
    "/v1/audio/speech": {
      "post": {
        "operationId": "createSpeech",
        "summary": "Synthesize speech from text",
        "requestBody": { "$ref": "#/components/requestBodies/SpeechRequest" },
        "responses": { "200": { "description": "Audio bytes in the requested supported format", "content": { "audio/mpeg": { "schema": { "type": "string", "contentEncoding": "binary" } }, "audio/wav": { "schema": { "type": "string", "contentEncoding": "binary" } }, "audio/ogg": { "schema": { "type": "string", "contentEncoding": "binary" } }, "application/octet-stream": { "schema": { "type": "string", "contentEncoding": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key" },
      "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" }
    },
    "parameters": {
      "TaskId": { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } }
    },
    "requestBodies": {
      "ResponseRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseRequest" } } } },
      "ChatRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest" } } } },
      "MessageRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageRequest" } } } },
      "ImageGenerationRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageRequest" } } } },
      "ImageEditRequest": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ImageEditRequest" } } } },
      "VideoRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoRequest" } } } },
      "SpeechRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpeechRequest" } } } }
    },
    "schemas": {
      "ModelList": { "type": "object", "required": ["object", "data"], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "required": ["id"], "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "owned_by": { "type": "string" }, "supported_endpoint_types": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } } }, "additionalProperties": true },
      "ResponseRequest": { "type": "object", "required": ["model", "input"], "properties": { "model": { "type": "string" }, "input": {}, "instructions": { "type": "string" }, "previous_response_id": { "type": "string" }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "tool_choice": {}, "reasoning": { "type": "object", "additionalProperties": true }, "service_tier": {}, "prompt_cache_key": { "type": "string" }, "prompt_cache_options": { "type": "object", "additionalProperties": true }, "prompt_cache_retention": { "type": "string" }, "stream": { "type": "boolean" }, "max_output_tokens": { "type": "integer", "minimum": 1 }, "store": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true }, "truncation": { "type": "string", "enum": ["auto", "disabled"], "default": "disabled" } }, "additionalProperties": true },
      "ChatRequest": { "type": "object", "required": ["model", "messages"], "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "required": ["role", "content"], "properties": { "role": { "type": "string" }, "content": {} }, "additionalProperties": true } }, "stream": { "type": "boolean" }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "tool_choice": {}, "reasoning_effort": { "type": "string" }, "service_tier": {}, "max_tokens": { "type": "integer", "minimum": 1 }, "max_completion_tokens": { "type": "integer", "minimum": 1 }, "temperature": { "type": "number" }, "top_p": { "type": "number" } }, "additionalProperties": true },
      "MessageRequest": { "type": "object", "required": ["model", "max_tokens", "messages"], "properties": { "model": { "type": "string" }, "max_tokens": { "type": "integer", "minimum": 1 }, "messages": { "type": "array", "items": { "type": "object", "required": ["role", "content"], "properties": { "role": { "type": "string", "enum": ["user", "assistant"] }, "content": {} }, "additionalProperties": true } }, "system": {}, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "tool_choice": {}, "thinking": { "type": "object", "additionalProperties": true }, "stream": { "type": "boolean" } }, "additionalProperties": true },
      "ImageRequest": { "type": "object", "required": ["model", "prompt"], "properties": { "model": { "type": "string" }, "prompt": { "type": "string" }, "image": { "description": "Seedream reference image URL/Data URL or array of up to 10 references.", "oneOf": [{ "type": "string" }, { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string" } }] }, "n": { "type": "integer", "minimum": 1, "maximum": 128 }, "size": { "type": "string" }, "quality": { "type": "string" }, "response_format": { "type": "string" }, "output_format": { "type": "string" }, "output_compression": { "type": "integer" }, "stream": { "type": "boolean" }, "partial_images": { "type": "integer" }, "background": {}, "moderation": {}, "watermark": { "type": "boolean" } }, "additionalProperties": true },
      "ImageEditRequest": { "type": "object", "required": ["model", "prompt", "image"], "properties": { "model": { "type": "string" }, "prompt": { "type": "string" }, "image": { "oneOf": [{ "type": "string", "contentEncoding": "binary" }, { "type": "array", "items": { "type": "string", "contentEncoding": "binary" } }] }, "mask": { "type": "string", "contentEncoding": "binary" }, "n": { "type": "integer", "minimum": 1, "maximum": 128 }, "size": { "type": "string" }, "quality": { "type": "string" }, "output_format": { "type": "string" }, "input_fidelity": { "type": "string" } }, "additionalProperties": true },
      "VideoRequest": { "type": "object", "required": ["model", "prompt"], "properties": { "model": { "type": "string" }, "prompt": { "type": "string" }, "duration": { "type": "integer", "minimum": 1, "maximum": 3600 }, "seconds": { "oneOf": [{ "type": "integer", "minimum": 1, "maximum": 3600 }, { "type": "string" }] }, "image": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "size": { "type": "string" }, "metadata": { "type": "object", "properties": { "resolution": { "type": "string" }, "ratio": { "type": "string" }, "content": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "generate_audio": { "type": "boolean" }, "watermark": { "type": "boolean" }, "service_tier": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true },
      "VideoTask": { "type": "object", "required": ["id", "object", "model", "status", "progress", "created_at"], "properties": { "id": { "type": "string" }, "task_id": { "type": "string", "deprecated": true }, "object": { "type": "string", "const": "video" }, "model": { "type": "string" }, "status": { "type": "string", "enum": ["unknown", "queued", "in_progress", "completed", "failed"] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "created_at": { "type": "integer" }, "completed_at": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": true }, "error": { "$ref": "#/components/schemas/ErrorDetail" } }, "additionalProperties": true },
      "SpeechRequest": { "type": "object", "required": ["model", "input", "voice"], "properties": { "model": { "type": "string", "const": "doubao-tts-2.0" }, "input": { "type": "string" }, "voice": { "type": "string", "examples": ["zh_female_vv_uranus_bigtts", "en_female_jane_uranus_bigtts"] }, "instructions": { "type": "string" }, "response_format": { "type": "string", "enum": ["mp3", "wav", "opus"] }, "speed": { "type": "number", "minimum": 0.5, "maximum": 2.0, "default": 1.0 }, "stream_format": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } }, "additionalProperties": true },
      "ImageResponse": { "type": "object", "required": ["created", "data"], "properties": { "created": { "type": "integer" }, "data": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "b64_json": { "type": "string" }, "revised_prompt": { "type": "string" } }, "additionalProperties": true } }, "usage": { "type": "object", "additionalProperties": true } }, "additionalProperties": true },
      "ErrorDetail": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" }, "param": {}, "code": {} }, "additionalProperties": true },
      "ErrorResponse": { "type": "object", "required": ["error"], "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail" } }, "additionalProperties": true }
    },
    "responses": {
      "JsonResponse": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } },
      "ResponseOrSSE": { "description": "Response object or SSE event stream", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/event-stream": { "schema": { "type": "string" } } } },
      "ChatOrSSE": { "description": "Chat completion or SSE chunks", "content": { "application/json": { "schema": { "type": "object", "properties": { "choices": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "usage": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } }, "text/event-stream": { "schema": { "type": "string" } } } },
      "JsonOrSSE": { "description": "JSON object or SSE event stream", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/event-stream": { "schema": { "type": "string" } } } },
      "ImageOrSSE": { "description": "Image result or partial-image SSE events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResponse" } }, "text/event-stream": { "schema": { "type": "string" } } } },
      "BadRequest": { "description": "Invalid request or unsupported model/parameter combination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
      "Unauthorized": { "description": "Missing, invalid, or disabled API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
      "Forbidden": { "description": "The API key is not allowed to use this model or group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
      "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
    }
  }
}