openapi: 3.0.3 info: title: GenieX Server version: 0.0.0 description: | GenieX Server - OpenAI compatible API endpoints paths: /v1/chat/completions: post: summary: Creates a model response for the given chat conversation description: This endpoint generates a model response for a given conversation, which can include text and images. It supports both single-turn and multi-turn conversations and can be used for various tasks like question answering, code generation, and function calling. operationId: PostV1ChatCompletions requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ChatCompletionRequest" responses: "200": description: Successful response for non-streaming requests content: application/json: schema: $ref: "#/components/schemas/ChatCompletionResponse" /v1/embeddings: post: summary: Creates an embedding for the given input description: Creates an embedding for the given input operationId: PostV1Embeddings requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/EmbeddingRequest" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/EmbeddingResponse" /v1/images/generations: post: summary: Creates an image given a prompt description: Creates an image given a prompt. This endpoint follows OpenAI DALL-E 3 API specification for compatibility. operationId: PostV1ImagesGenerations requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ImageGenerationRequest" responses: "200": description: Successful image generation response content: application/json: schema: $ref: "#/components/schemas/ImageGenerationResponse" "400": description: Bad request - invalid parameters content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: Model not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /v1/reranking: post: summary: Rerank documents based on their relevance to a query description: Reranks a list of documents according to their semantic relevance to the provided query. Returns relevance scores for each document. Higher scores indicate greater relevance. operationId: PostV1Reranking requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/RerankingRequest" example: model: "NexaAI/jina-v2-rerank-npu" query: "What is machine learning?" documents: - "Machine learning is a subset of artificial intelligence." - "Machine learning algorithms learn patterns from data." - "The weather is sunny today." - "Deep learning is a type of machine learning." batch_size: 4 normalize: true normalize_method: "softmax" responses: "200": description: Successfully reranked documents with relevance scores content: application/json: schema: $ref: "#/components/schemas/RerankingResponse" example: result: [0.95, 0.92, 0.10, 0.88] "400": description: Bad request - invalid parameters content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /v1/audio/speech: post: summary: Generates audio from the input text description: | Creates audio from the given text using text-to-speech. When stream_format is omitted or not "sse", returns raw WAV binary. When stream_format is "sse", returns Server-Sent Events stream with speech.audio.delta (base64 audio chunks) and speech.audio.done (usage). Empty input returns 200 with null (warm up). operationId: PostV1AudioSpeech parameters: - name: GenieX-KeepCache in: header required: false schema: type: string description: If "true", keeps the model in cache after use requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AudioSpeechRequest" responses: "200": description: Successful audio generation. Binary WAV when stream_format is not sse; SSE stream when stream_format is sse; null body for warm up. content: audio/wav: schema: type: string format: binary text/event-stream: schema: type: string description: SSE events - speech.audio.delta { type, audio (base64) }, speech.audio.done { type, usage } "400": description: Bad request - invalid parameters content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /v1/audio/transcriptions: post: summary: Transcribes audio into the input language description: | Transcribes audio files into text using ASR. Request must be multipart/form-data with model and file. stream=true is not supported (returns 400). Omit file for warm up (returns 200 with null). operationId: PostV1AudioTranscriptions requestBody: required: true content: multipart/form-data: schema: $ref: "#/components/schemas/AudioTranscriptionRequest" responses: "200": description: Successful transcription (or null body when no file sent for warm up) content: application/json: schema: $ref: "#/components/schemas/AudioTranscriptionResponse" "400": description: Bad request - invalid parameters, or stream=true (streaming not supported) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /v1/audio/diarize: post: summary: Performs speaker diarization on audio description: | Identifies and separates different speakers in an audio file. Audio can be base64 data URL or URL. Empty audio returns 200 with null (warm up). operationId: PostV1AudioDiarize requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AudioDiarizeRequest" responses: "200": description: Successful diarization with segments, num_speakers, duration (or null body for warm up) content: application/json: schema: $ref: "#/components/schemas/AudioDiarizeResponse" "400": description: Bad request - invalid parameters or failed to save audio content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /v1/cv: post: summary: Performs computer vision analysis on images description: Analyzes images using computer vision models for various tasks like object detection, classification, etc. operationId: PostV1CV requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CVRequest" responses: "200": description: Successful computer vision analysis content: application/json: schema: $ref: "#/components/schemas/CVResponse" "400": description: Bad request - invalid parameters content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /v1/models: get: summary: Lists the currently available models description: Lists the currently available models, and provides basic information about each one such as the owner and availability operationId: GetV1Models responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ModelsListResponse" /v1/models/{model}: get: summary: Retrieves a model instance description: Retrieves a model instance, providing basic information about the model such as the owner and permissioning operationId: GetV1ModelsModel parameters: - name: model in: path required: true description: The ID of the model to use for this request schema: type: string responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ModelResponse" "404": description: Model not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" components: schemas: # ---------- Chat ---------- ChatCompletionRequest: type: object required: [model, messages] properties: model: type: string description: ID of the model to use default: "Qwen/Qwen3-1.7B-GGUF" messages: type: array items: $ref: "#/components/schemas/ChatMessage" description: A list of messages comprising the conversation so far nctx: type: integer minimum: 1 description: The maximum number of tokens that can be processed in the chat completion default: 4096 max_completion_tokens: type: integer minimum: 1 description: An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens. default: 2048 temperature: type: number format: float minimum: 0 maximum: 2 default: 0.8 description: What sampling temperature to use, between 0 and 2 top_p: type: number format: float minimum: 0 maximum: 1 default: 0.95 description: An alternative to sampling with temperature, called nucleus sampling n: type: integer minimum: 1 description: How many chat completion choices to generate for each input message default: 1 stream: type: boolean description: If set, partial message deltas will be sent default: false stop: oneOf: - type: string - type: array items: { type: string } description: Up to 4 sequences where the API will stop generating further tokens default: "" presence_penalty: type: number format: float minimum: -2 maximum: 2 default: 0.0 description: Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far frequency_penalty: type: number format: float minimum: -2 maximum: 2 default: 0.0 description: Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far logit_bias: type: object additionalProperties: type: integer description: Modify the likelihood of specified tokens appearing in the completion user: type: string description: A unique identifier representing your end-user default: "role" tools: type: array items: $ref: "#/components/schemas/ChatCompletionTool" description: A list of tools the model may call default: [] tool_choice: oneOf: - type: string - $ref: "#/components/schemas/ChatCompletionToolChoice" description: Controls which (if any) function is called by the model default: "" enable_json: type: boolean description: Whether to enable JSON response generation default: false enable_think: type: boolean description: Whether to enable thinking mode for the model default: true top_k: type: integer minimum: 0 description: An alternative to sampling with temperature, called top-k sampling default: 0 min_p: type: number format: float minimum: 0 maximum: 1 description: An alternative to sampling with temperature, called nucleus sampling default: 0.0 repetition_penalty: type: number format: float minimum: 0 maximum: 100 description: The parameter for repetition penalty. 1.0 means no penalty default: 1.0 grammar_path: type: string description: Path to the grammar file for structured output default: "" grammar_string: type: string description: Grammar string for structured output default: "" ngl: type: integer description: Number of GPU layers to use default: 999 image_max_length: type: integer description: Maximum length for image processing default: 512 ChatMessage: type: object required: [role, content] default: { "role": "user", "content": "What is the weather like in Boston today?", } properties: role: type: string enum: [system, user, assistant, tool] description: The role of the author of this message content: oneOf: - type: string - type: array items: $ref: "#/components/schemas/ChatMessageContent" description: The contents of the message name: type: string description: The name of the author of this message tool_calls: type: array items: $ref: "#/components/schemas/ChatCompletionMessageToolCall" description: The tool calls generated by the model function_call: $ref: "#/components/schemas/ChatCompletionMessageFunctionCall" description: Deprecated and replaced by tool_calls ChatMessageContent: type: object properties: type: type: string enum: [text, image_url, input_audio] text: type: string image_url: $ref: "#/components/schemas/ChatMessageImageURL" input_audio: $ref: "#/components/schemas/ChatMessageAudioURL" ChatMessageImageURL: type: object properties: url: type: string detail: type: string enum: [low, high, auto] ChatMessageAudioURL: type: object properties: data: type: string description: The audio data (base64 encoded or URL) ChatCompletionTool: type: object properties: type: type: string enum: [function] function: $ref: "#/components/schemas/ChatCompletionToolFunction" ChatCompletionToolFunction: type: object required: [name] properties: name: type: string description: The name of the function to be called description: type: string description: A description of what the function does parameters: type: object description: The parameters the functions accepts ChatCompletionToolChoice: type: object properties: type: type: string enum: [function] function: type: object properties: name: type: string ChatCompletionMessageToolCall: type: object properties: id: type: string description: The ID of the tool call type: type: string enum: [function] description: The type of the tool function: $ref: "#/components/schemas/ChatCompletionMessageToolCallFunction" ChatCompletionMessageToolCallFunction: type: object properties: name: type: string description: The name of the function to call arguments: type: string description: The arguments to call the function with, as generated by the model in JSON format ChatCompletionMessageFunctionCall: type: object properties: name: type: string description: The name of the function to call arguments: type: string description: The arguments to call the function with, as generated by the model in JSON format ChatCompletionResponse: type: object required: [choices] properties: id: type: string description: A unique identifier for the chat completion object: type: string description: The object type, which is always "chat.completion" created: type: integer description: The Unix timestamp (in seconds) of when the chat completion was created model: type: string description: The model used for the chat completion choices: type: array items: $ref: "#/components/schemas/ChatChoice" description: A list of chat completion choices usage: $ref: "#/components/schemas/TokenUsage" ChatChoice: type: object properties: index: type: integer description: The index of the choice in the list of choices message: $ref: "#/components/schemas/ChatMessage" description: A chat completion message generated by the model finish_reason: type: string enum: [stop, length, tool_calls, content_filter, function_call] description: The reason the model stopped generating tokens logprobs: $ref: "#/components/schemas/ChatCompletionChoiceLogprobs" ChatCompletionChoiceLogprobs: type: object properties: content: type: array items: $ref: "#/components/schemas/ChatCompletionTokenLogprob" ChatCompletionTokenLogprob: type: object properties: token: type: string logprob: type: number bytes: type: array items: type: integer top_logprobs: type: array items: $ref: "#/components/schemas/ChatCompletionTokenLogprobTopLogprob" ChatCompletionTokenLogprobTopLogprob: type: object properties: token: type: string logprob: type: number bytes: type: array items: type: integer # ---------- Embeddings ---------- EmbeddingRequest: type: object required: [model, input] properties: model: type: string description: ID of the model to use default: "djuna/jina-embeddings-v2-small-en-Q5_K_M-GGUF" input: oneOf: - type: string - type: array items: { type: string } - type: array items: { type: integer } - type: array items: type: array items: { type: integer } description: Input text to embed default: "Hello, world!" encoding_format: type: string enum: [float, base64] description: The format to return the embeddings in dimensions: type: integer description: The number of dimensions the resulting output embeddings should have user: type: string description: A unique identifier representing your end-user task_type: type: string description: The type of task for the embedding default: "default" EmbeddingResponse: type: object required: [data] properties: object: type: string description: The object type, which is always "list" data: type: array items: $ref: "#/components/schemas/EmbeddingVector" description: The list of embeddings generated by the model model: type: string description: The name of the model used to generate the embedding usage: $ref: "#/components/schemas/TokenUsage" EmbeddingVector: type: object required: [embedding] properties: object: type: string description: The object type, which is always "embedding" embedding: type: array items: { type: number, format: float } description: The embedding vector index: type: integer description: The index of the embedding in the list of embeddings # ---------- Image Generation ---------- ImageGenerationRequest: type: object required: [model, prompt] properties: model: type: string description: ID of the model to use default: "nexaml/sdxl-turbo-ryzen-ai" prompt: type: string description: A text description of the desired image(s). The maximum length is 1000 characters. default: "A white cat with red eyes" n: type: integer minimum: 1 maximum: 10 description: The number of images to generate. Must be between 1 and 10. default: 1 size: type: string enum: ["256x256", "512x512", "1024x1024", "1792x1024", "1024x1792"] description: The size of the generated images. Must be one of the supported sizes. default: "256x256" quality: type: string enum: ["standard", "hd"] description: The quality of the image that will be generated default: "standard" style: type: string enum: ["vivid", "natural"] description: The style of the generated images default: "vivid" response_format: type: string enum: ["b64_json"] description: The format in which the generated images are returned default: "b64_json" user: type: string description: A unique identifier representing your end-user ImageGenerationResponse: type: object required: [created, data] properties: created: type: integer description: The Unix timestamp (in seconds) of when the image was created data: type: array items: $ref: "#/components/schemas/ImageGenerationData" description: The list of generated images ImageGenerationData: type: object properties: b64_json: type: string description: The base64-encoded JSON of the generated image revised_prompt: type: string description: The prompt that was used to generate the image, if there was a revision to the prompt # ---------- Reranking ---------- RerankingRequest: type: object required: [model] properties: model: type: string description: ID of the reranking model to use default: "NexaAI/jina-v2-rerank-npu" example: "NexaAI/jina-v2-rerank-npu" query: type: string description: The search query to compare documents against default: "What is machine learning?" example: "What is machine learning?" documents: type: array items: { type: string } description: A list of documents to rerank based on relevance to the query example: - "Machine learning is a subset of artificial intelligence." - "Machine learning algorithms learn patterns from data." - "The weather is sunny today." - "Deep learning is a type of machine learning." batch_size: type: integer description: The batch size to use for reranking default: 4 example: 4 normalize: type: boolean description: Whether to normalize the relevance scores default: false example: true normalize_method: type: string description: The normalization method to apply to scores enum: [softmax, linear] default: "softmax" example: "softmax" RerankingResponse: type: object required: [result] properties: result: type: array items: type: number format: float description: Array of relevance scores corresponding to each document in the input. Higher scores indicate greater relevance to the query. example: [0.95, 0.92, 0.10, 0.88] # ---------- Common ---------- ErrorResponse: type: object required: [error] properties: error: type: string description: Error message describing what went wrong TokenUsage: type: object properties: prompt_tokens: type: integer description: Number of tokens in the prompt completion_tokens: type: integer description: Number of tokens in the generated completion total_tokens: type: integer description: Total number of tokens used in the request # ---------- Audio ---------- AudioSpeechRequest: type: object required: [model, input] properties: model: type: string description: ID of the model to use default: "nexaml/Kokoro-82M-bf16" input: type: string description: The text to generate audio for. Empty for warm up (returns null). voice: type: string description: The voice to use when generating the audio response_format: type: string enum: [wav] description: The format to return the audio in (when not streaming) default: "wav" stream_format: type: string enum: [wav, sse] description: '"sse" returns Server-Sent Events stream; otherwise returns binary WAV' speed: type: number format: float minimum: 0.25 maximum: 4.0 description: The speed of the generated audio default: 1.0 AudioTranscriptionRequest: type: object description: multipart/form-data form fields required: [model] properties: model: type: string description: ID of the model to use default: "NexaAI/parakeet-tdt-0.6b-v3-npu" file: type: string format: binary description: The audio file to transcribe. Omit for warm up (returns null). stream: type: string description: '"true" is not supported and returns 400' language: type: string description: The language of the input audio prompt: type: string description: An optional text to guide the model's style or continue a previous audio segment response_format: type: string enum: [json, text, srt, verbose_json, vtt] description: The format of the transcript output default: "text" temperature: type: number format: float minimum: 0 maximum: 1 description: The sampling temperature default: 0.0 AudioTranscriptionResponse: type: object properties: text: type: string description: The transcribed text AudioDiarizeRequest: type: object required: [model] properties: model: type: string description: ID of the model to use default: "nexaml/pyannote-npu" audio: type: string description: The audio to diarize (base64 data URL or URL). Empty for warm up (returns null). AudioDiarizeResponse: type: object properties: segments: type: array items: $ref: "#/components/schemas/DiarizeSegment" description: Speaker segments with time ranges num_speakers: type: integer format: int32 description: Number of speakers detected duration: type: number format: float description: Audio duration in seconds DiarizeSegment: type: object properties: start_time: type: number format: float description: Start time in seconds end_time: type: number format: float description: End time in seconds speaker_label: type: string description: The speaker identifier for this segment # ---------- Computer Vision ---------- CVRequest: type: object required: [model, image] properties: model: type: string description: ID of the model to use default: "NexaAI/paddleocr-npu" image: type: string description: The image data to analyze (base64 encoded or URL) CVResponse: type: object properties: results: type: array items: $ref: "#/components/schemas/CVResult" CVResult: type: object properties: label: type: string description: The detected label or class confidence: type: number format: float description: The confidence score bbox: type: object properties: x: type: number format: float y: type: number format: float width: type: number format: float height: type: number format: float description: Bounding box coordinates # ---------- Models ---------- ModelsListResponse: type: object properties: object: type: string description: The object type, which is always "list" data: type: array items: $ref: "#/components/schemas/Model" ModelResponse: type: object properties: id: type: string description: The model identifier object: type: string description: The object type, which is always "model" owned_by: type: string description: The organization that owns the model created: type: integer description: The Unix timestamp (in seconds) of when the model was created permission: type: array items: type: object description: The permissions associated with the model Model: type: object properties: id: type: string description: The model identifier owned_by: type: string description: The organization that owns the model