{ "openapi": "3.1.0", "info": { "title": "AI Studio API", "version": "0.1", "description": "The AI Studio API is a REST API for the full lifecycle of custom AI models on Hyperstack AI Studio: curate and generate training datasets, fine-tune foundation models on your data, evaluate training results, deploy models, and run inference. Inference runs on base and fine-tuned models, covering text chat (OpenAI-compatible chat completions) and image generation and editing.\n\n## Base URL\n\nAll requests are sent to:\n\n```\nhttps://console.hyperstack.cloud/ai/api/v1\n```\n\n## Authentication\n\nEvery request requires an API key. Pass it as the `api_key` request header, with the raw key as the value and no prefix (`api_key: YOUR_API_KEY`). Generate a key on the [API Keys](https://console.hyperstack.cloud/api-keys) page in the Hyperstack console. See [Getting Started with the API](https://docs.hyperstack.cloud/docs/ai-studio/getting-started#getting-started-with-the-api) for the full walkthrough.\n\n## Request and response format\n\nRequests use standard HTTP methods (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) with `application/json` bodies unless noted otherwise. Responses are `application/json`. The text inference endpoints, such as [chat completions](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/chat-completions), are OpenAI-compatible." }, "servers": [ { "url": "https://console.hyperstack.cloud/ai/api/v1" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Base Models", "description": "Pre-trained foundation models available in AI Studio. These endpoints let you list available models, retrieve pricing, and fetch details for a specific base model." }, { "name": "Inference", "description": "OpenAI-compatible chat completions endpoint for running inference against deployed models. Use this endpoint to send prompts and receive generated responses." }, { "name": "Image Generation", "description": "Text-to-image and image-to-image generation. Submit a generation or edit request, then poll the task endpoint to retrieve the resulting image. Use a presigned upload URL to supply a source image for edits." }, { "name": "Conversations", "description": "Conversation threads and message history for AI Studio chat sessions. These endpoints let you create conversations, send messages, retrieve message history, and delete conversation threads." }, { "name": "Models", "description": "User-deployed models and model aliases. These endpoints let you deploy and undeploy models, list available models, manage model aliases, and retrieve deployment details." }, { "name": "System Prompts", "description": "Reusable system prompt templates for AI Studio deployments. These endpoints let you create, retrieve, update, and delete system prompts that can be applied to deployed models." }, { "name": "Overview", "description": "Organization-level summary and resource usage metrics for the AI Studio account." }, { "name": "Knowledge Bases", "description": "Collections of your own documents that models can search at inference time." } ], "paths": { "/base_models": { "get": { "description": "Returns all pre-trained foundation models available in AI Studio for inference. Base models are served through third-party provider integrations.", "operationId": "getBaseModels", "parameters": [ { "in": "query", "name": "inference", "required": false, "schema": { "type": "boolean", "default": null }, "description": "When `true`, returns only base models that are available for inference." }, { "in": "query", "name": "finetuning", "required": false, "schema": { "type": "boolean", "default": null }, "description": "When `true`, returns only base models that support fine-tuning." }, { "in": "query", "name": "modalities", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ModalityEnum" } }, "description": "Filter models by modality. Repeat the parameter for multiple values, such as `modalities=text-to-image&modalities=image-to-image`." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseModelsResponseSchema", "example": { "models": [ { "allowed_hf_lora_adapter_size": 8589934592, "available_for_finetuning": true, "available_for_inference": true, "default_batch_size": 16, "default_gradient_accumulation_steps": 2, "default_lr": 0.00005, "default_micro_batch_size": 4, "deployment_records": [], "display_name": "Llama 3.3 70B Instruct", "hf_repo": "meta-llama/Llama-3.3-70B-Instruct", "input_token_cost_per_m": 0.8, "is_third_party": false, "model_id": 1001, "model_name": "Llama-3.3-70B-Instruct", "model_type": "language_model", "output_token_cost_per_m": 0.8, "supported_context_len": 8192, "supported_locations": [ "ca1" ], "training_cost_per_log": 0.00551, "training_time_per_log": 0.08741, "training_time_y_intercept": 856.518, "input_modalities": [ "text" ], "output_modalities": [ "text" ] } ], "status": "success" } }, "example": { "models": [ { "allowed_hf_lora_adapter_size": 8589934592, "available_for_finetuning": true, "available_for_inference": true, "default_batch_size": 16, "default_gradient_accumulation_steps": 2, "default_lr": 0.00005, "default_micro_batch_size": 4, "deployment_records": [], "display_name": "Llama 3.3 70B Instruct", "hf_repo": "meta-llama/Llama-3.3-70B-Instruct", "input_token_cost_per_m": 0.8, "is_third_party": false, "model_id": 1001, "model_name": "Llama-3.3-70B-Instruct", "model_type": "language_model", "output_token_cost_per_m": 0.8, "supported_context_len": 8192, "supported_locations": [ "ca1" ], "training_cost_per_log": 0.00551, "training_time_per_log": 0.08741, "training_time_y_intercept": 856.518, "input_modalities": [ "text" ], "output_modalities": [ "text" ] } ], "status": "success" } } }, "description": "OK" }, "422": { "description": "Validation Error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Internal Server Error" } }, "summary": "List base models", "tags": [ "Base Models" ] } }, "/base_models/pricing": { "get": { "description": "Returns input and output token pricing for each available base model, expressed as cost per 1 million tokens. Use this to estimate inference and evaluation costs before submitting jobs.", "operationId": "getBaseModelPricing", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "pricing": [ { "available_for_inference": true, "is_third_party": false, "last_health_check": "2025-01-15T10:30:00.000000+00:00", "model_name": "Llama-3.3-70B-Instruct", "pricing": { "input": "0.80", "output": "0.80" } } ], "status": "success" }, "schema": { "type": "object", "properties": { "pricing": { "type": "array", "description": "List of pricing entries, one per available model.", "items": { "type": "object", "properties": { "available_for_inference": { "type": "boolean", "description": "Whether the model is currently available for inference." }, "is_third_party": { "type": "boolean", "description": "Whether the model is hosted by a third-party provider." }, "last_health_check": { "type": "string", "description": "ISO 8601 timestamp of the most recent availability health check." }, "model_name": { "type": "string", "description": "Model display name." }, "pricing": { "type": "object", "description": "Token pricing in USD per 1 million tokens.", "properties": { "input": { "type": "string", "description": "Cost per 1M input (prompt) tokens." }, "output": { "type": "string", "description": "Cost per 1M output (completion) tokens." } } } } } }, "status": { "type": "string", "description": "Indicates the result of the operation. Typically `\"success\"`." } }, "example": { "pricing": [ { "available_for_inference": true, "is_third_party": false, "last_health_check": "2025-01-15T10:30:00.000000+00:00", "model_name": "Llama-3.3-70B-Instruct", "pricing": { "input": "0.80", "output": "0.80" } } ], "status": "success" } } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Not Found" }, "422": { "description": "Validation Error" } }, "summary": "List base model pricing", "tags": [ "Base Models" ] } }, "/base_models/{base_model_id}": { "get": { "description": "Returns detailed information for a specific base model by its numeric ID, including supported context length and pricing tiers.", "operationId": "getBaseModel", "parameters": [ { "in": "path", "name": "base_model_id", "required": true, "schema": { "format": "int32", "type": "integer" }, "description": "Unique identifier of the base model to retrieve." }, { "in": "query", "name": "month", "required": false, "schema": { "type": "integer", "default": null }, "description": "Month (1-12) to scope returned usage data to." }, { "in": "query", "name": "year", "required": false, "schema": { "type": "integer", "default": null }, "description": "Year (e.g. `2025`) to scope returned usage data to." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetModelResponseSchema", "example": { "message": { "allowed_hf_lora_adapter_size": 8589934592, "available_for_finetuning": true, "available_for_inference": true, "default_batch_size": 16, "default_gradient_accumulation_steps": 2, "default_lr": 0.00005, "default_micro_batch_size": 4, "deployment_records": [], "display_name": "Llama 3.3 70B Instruct", "hf_repo": "meta-llama/Llama-3.3-70B-Instruct", "input_token_cost_per_m": 0.8, "is_third_party": false, "model_id": 1001, "model_name": "Llama-3.3-70B-Instruct", "model_type": "language_model", "output_token_cost_per_m": 0.8, "supported_context_len": 8192, "supported_locations": [ "ca1" ], "training_cost_per_log": 0.00551, "training_time_per_log": 0.08741, "training_time_y_intercept": 856.518, "usage_data": [], "input_modalities": [ "text" ], "output_modalities": [ "text" ] }, "status": "success" } }, "example": { "message": { "allowed_hf_lora_adapter_size": 8589934592, "available_for_finetuning": true, "available_for_inference": true, "default_batch_size": 16, "default_gradient_accumulation_steps": 2, "default_lr": 0.00005, "default_micro_batch_size": 4, "deployment_records": [], "display_name": "Llama 3.3 70B Instruct", "hf_repo": "meta-llama/Llama-3.3-70B-Instruct", "input_token_cost_per_m": 0.8, "is_third_party": false, "model_id": 1001, "model_name": "Llama-3.3-70B-Instruct", "model_type": "language_model", "output_token_cost_per_m": 0.8, "supported_context_len": 8192, "supported_locations": [ "ca1" ], "training_cost_per_log": 0.00551, "training_time_per_log": 0.08741, "training_time_y_intercept": 856.518, "usage_data": [], "input_modalities": [ "text" ], "output_modalities": [ "text" ] }, "status": "success" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Not Found" }, "422": { "description": "Validation Error" } }, "summary": "Get base model", "tags": [ "Base Models" ] } }, "/chat/completions": { "post": { "description": "Sends a chat prompt to a model and returns a completion. Supports both streaming (server-sent events) and non-streaming response modes. Use the `model` field to target a base model by its `model_name`. Optional sampling parameters include `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, and `repetition_penalty`. Total tokens (prompt + completion) must not exceed the model's context window.", "operationId": "chatCompletions", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InferenceRequestSchema", "example": { "model": "Qwen/Qwen3-VL-8B-Instruct", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe this image." }, { "type": "image_url", "image_url": { "url": "https://example.com/photo.png" } } ] } ], "stream": false } }, "example": { "model": "Qwen/Qwen3-VL-8B-Instruct", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe this image." }, { "type": "image_url", "image_url": { "url": "https://example.com/photo.png" } } ] } ], "stream": false } } } }, "responses": { "200": { "content": { "application/json": { "example": { "choices": [ { "finish_reason": "stop", "index": 0, "message": { "content": "This is a minimalist, pixel-art style image depicting a serene sunset or sunrise over a mountain range.\n\nThe key elements are:\n\n* **The Sky:** The background features a smooth gradient, transitioning from a deep purple at the top to a warm orange-pink near the horizon. This creates a calm, atmospheric effect.\n* **The Sun:** A large, bright, off-white circle representing the sun is positioned just above the horizon, partially obscured by the mountains.\n* **The Mountains:** Two simple, dark purple, triangular mountain silhouettes dominate the lower half of the image. They are rendered in a low-resolution, pixelated style, giving the scene a retro video game aesthetic.\n\nThe overall composition is balanced and tranquil, with the sun acting as a central focal point. The use of simple shapes and a limited color palette emphasizes the peacefulness of the scene.", "role": "assistant" } } ], "created": 1736932200, "id": "a1b2c3d4e5f6789012345678901234ab", "model": "qwen/qwen3-vl-8b-instruct", "object": "chat.completion", "usage": { "completion_tokens": 177, "prompt_tokens": 91, "total_tokens": 268 } }, "schema": { "type": "object", "description": "OpenAI-compatible chat completion response.", "properties": { "choices": { "type": "array", "description": "Array of completion choices. Most requests produce one choice.", "items": { "type": "object", "properties": { "finish_reason": { "type": "string", "description": "Reason generation stopped: `stop`, `length`, or `content_filter`." }, "index": { "type": "integer", "description": "Index of this choice." }, "logprobs": { "type": "object", "description": "Log probabilities for tokens, if requested." }, "message": { "type": "object", "description": "The generated message.", "properties": { "role": { "type": "string", "description": "Always `\"assistant\"`." }, "content": { "type": "string", "description": "Generated text content." } } } } } }, "created": { "type": "integer", "description": "Unix timestamp of when the completion was created." }, "id": { "type": "string", "description": "Unique identifier for this completion." }, "model": { "type": "string", "description": "Model that generated the completion." }, "object": { "type": "string", "description": "Always `\"chat.completion\"`." }, "usage": { "type": "object", "description": "Token usage for this completion.", "properties": { "prompt_tokens": { "type": "integer", "description": "Tokens in the input prompt." }, "completion_tokens": { "type": "integer", "description": "Tokens generated in the response." }, "total_tokens": { "type": "integer", "description": "Total tokens consumed." } } } }, "example": { "choices": [ { "finish_reason": "stop", "index": 0, "message": { "content": "This is a minimalist, pixel-art style image depicting a serene sunset or sunrise over a mountain range.\n\nThe key elements are:\n\n* **The Sky:** The background features a smooth gradient, transitioning from a deep purple at the top to a warm orange-pink near the horizon. This creates a calm, atmospheric effect.\n* **The Sun:** A large, bright, off-white circle representing the sun is positioned just above the horizon, partially obscured by the mountains.\n* **The Mountains:** Two simple, dark purple, triangular mountain silhouettes dominate the lower half of the image. They are rendered in a low-resolution, pixelated style, giving the scene a retro video game aesthetic.\n\nThe overall composition is balanced and tranquil, with the sun acting as a central focal point. The use of simple shapes and a limited color palette emphasizes the peacefulness of the scene.", "role": "assistant" } } ], "created": 1736932200, "id": "a1b2c3d4e5f6789012345678901234ab", "model": "qwen/qwen3-vl-8b-instruct", "object": "chat.completion", "usage": { "completion_tokens": 177, "prompt_tokens": 91, "total_tokens": 268 } } } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "The request was invalid. This includes sending image content to a model that does not support image input, which returns the error \"Model X does not support image input.\"" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Not Found" }, "422": { "description": "Validation Error" } }, "summary": "Create chat completion", "tags": [ "Inference" ] } }, "/conversations": { "get": { "description": "Returns all conversation threads for the authenticated user. Conversations are persistent chat sessions, created in the AI Studio Playground or via the Send message API, that retain message history, model selection, and parameter settings across sessions.", "operationId": "getConversations", "parameters": [ { "in": "query", "name": "page", "required": false, "description": "Page number to retrieve. Defaults to 1.", "schema": { "type": "integer", "default": 1 } }, { "in": "query", "name": "per_page", "required": false, "description": "Number of conversations per page. Defaults to 20.", "schema": { "type": "integer", "default": 20 } }, { "in": "query", "name": "search", "required": false, "description": "Filter conversations by title (case-insensitive).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A paginated list of your conversations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversations": { "type": "array", "description": "The conversations on this page, ordered by most recent activity.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique conversation ID." }, "title": { "type": "string", "description": "Conversation title, generated automatically from the first message and editable via the rename endpoint." }, "model_name": { "type": "string", "description": "The model used in the conversation." }, "base_model_id": { "type": "integer", "description": "ID of the base model used in the conversation." }, "message_count": { "type": "integer", "description": "Number of messages in the conversation." }, "last_message_preview": { "type": "string", "description": "A short preview of the most recent message." }, "settings": { "type": "object", "description": "Inference settings applied to the conversation, such as temperature or top_p." }, "system_prompt_id": { "type": "integer", "nullable": true, "description": "ID of the saved system prompt applied to the conversation, or null if none." }, "created_at": { "type": "string", "description": "When the conversation was created." }, "modified_at": { "type": "string", "nullable": true, "description": "When the conversation was last updated, or null if it has not changed since creation." }, "is_deleted": { "type": "boolean", "description": "Whether the conversation has been soft-deleted." }, "deleted_at": { "type": "string", "nullable": true, "description": "When the conversation was deleted, or null if it has not been deleted." }, "user_id": { "type": "integer", "description": "ID of the user who owns the conversation." }, "organization_id": { "type": "integer", "description": "ID of the organization that owns the conversation." }, "lorax_model_id": { "type": "integer", "nullable": true, "description": "ID of the LoRA-served fine-tuned model used for the conversation, or null if not applicable." } } } }, "page": { "type": "integer", "description": "The current page number." }, "pages": { "type": "integer", "description": "Total number of pages." }, "per_page": { "type": "integer", "description": "Number of conversations per page." }, "total": { "type": "integer", "description": "Total number of conversations." } }, "example": { "conversations": [ { "id": 1001, "title": "Describe the attached image", "model_name": "Qwen/Qwen3-VL-8B-Instruct", "base_model_id": 1001, "message_count": 1, "last_message_preview": "This image is a stylized, pixel-art depiction of a sunset over mountains.", "settings": {}, "system_prompt_id": null, "created_at": "Wed, 15 Jan 2025 10:30:00 GMT", "modified_at": "Wed, 15 Jan 2025 10:31:00 GMT", "is_deleted": false, "deleted_at": null, "user_id": 1001, "organization_id": 1001, "lorax_model_id": null } ], "page": 1, "pages": 1, "per_page": 20, "total": 1 } }, "example": { "conversations": [ { "id": 1001, "title": "Describe the attached image", "model_name": "Qwen/Qwen3-VL-8B-Instruct", "base_model_id": 1001, "message_count": 1, "last_message_preview": "This image is a stylized, pixel-art depiction of a sunset over mountains.", "settings": {}, "system_prompt_id": null, "created_at": "Wed, 15 Jan 2025 10:30:00 GMT", "modified_at": "Wed, 15 Jan 2025 10:31:00 GMT", "is_deleted": false, "deleted_at": null, "user_id": 1001, "organization_id": 1001, "lorax_model_id": null } ], "page": 1, "pages": 1, "per_page": 20, "total": 1 } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Not Found" }, "422": { "description": "Validation Error" } }, "summary": "List conversations", "tags": [ "Conversations" ] } }, "/conversations/send_message": { "post": { "description": "Sends a message to a conversation thread and returns the model's response. If `conversation_id` is omitted or null, a new conversation thread is created. Supports both streaming and non-streaming response modes via the `stream` flag. An optional `system_prompt_id` attaches a saved system prompt template to the request.", "operationId": "sendMessage", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationSendMessageRequestSchema", "example": { "message": "What is in this image?", "model": "Qwen/Qwen3-VL-8B-Instruct", "image_attachments": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ], "stream": false } }, "example": { "message": "What is in this image?", "model": "Qwen/Qwen3-VL-8B-Instruct", "image_attachments": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ], "stream": false } } } }, "responses": { "200": { "content": { "application/json": { "example": { "choices": [ { "finish_reason": "stop", "index": 0, "message": { "content": "This image is a stylized, pixel-art depiction of a sunset or sunrise over mountains.\n\nHere's a breakdown of what's in the image:\n\n- **The Sun:** A large, pale yellow/cream-colored circle sits just above the mountain ridge, appearing to be setting or rising.\n- **The Mountains:** Two dark purple, jagged peaks form the foreground. The silhouette suggests a simple, stylized mountain range.\n- **The Sky:** The background sky features a gradient of colors, transitioning from deep purple at the top to a warm orange/pink near the horizon where the sun is located.\n\nThe overall aesthetic is minimalist and retro, reminiscent of early video game graphics or digital art with a pixelated style. It evokes a sense of calm and natural beauty through its simple composition.", "role": "assistant" } } ], "conversation": { "id": 1001, "title": "Image content unknown." }, "created": 1736932200, "id": "a1b2c3d4e5f6789012345678901234ab", "model": "qwen/qwen3-vl-8b-instruct", "object": "chat.completion", "system_fingerprint": "", "usage": { "completion_tokens": 159, "completion_tokens_details": { "accepted_prediction_tokens": 0, "audio_tokens": 0, "image_tokens": 0, "reasoning_tokens": 0, "rejected_prediction_tokens": 0, "text_tokens": 159, "video_tokens": 0 }, "prompt_tokens": 93, "prompt_tokens_details": { "audio_tokens": 0, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "cached_tokens": 0, "image_tokens": 79, "text_tokens": 14, "video_tokens": 0 }, "total_tokens": 252 } }, "schema": { "type": "object", "properties": { "choices": { "type": "array", "description": "Array of completion choices (typically one).", "items": { "type": "object", "properties": { "finish_reason": { "type": "string", "description": "Reason the model stopped generating tokens (e.g. `stop`, `length`)." }, "index": { "type": "integer", "description": "Index of this choice in the array." }, "message": { "type": "object", "description": "The generated assistant message.", "properties": { "role": { "type": "string", "description": "Always `\"assistant\"`." }, "content": { "type": "string", "description": "The text content of the generated response." } } } } } }, "conversation": { "type": "object", "description": "The conversation this message belongs to.", "properties": { "id": { "type": "integer", "description": "Unique conversation ID." }, "title": { "type": "string", "description": "Conversation title, generated automatically from the first message and editable via the rename endpoint." } } }, "created": { "type": "integer", "description": "Unix timestamp of when the completion was created." }, "model": { "type": "string", "description": "Model used for this completion." }, "usage": { "type": "object", "description": "Token usage statistics for this completion.", "properties": { "prompt_tokens": { "type": "integer", "description": "Tokens in the prompt." }, "completion_tokens": { "type": "integer", "description": "Tokens in the generated response." }, "total_tokens": { "type": "integer", "description": "Total tokens consumed." }, "completion_tokens_details": { "type": "object", "description": "Breakdown of the completion (output) token count by category.", "properties": { "accepted_prediction_tokens": { "type": "integer", "description": "Tokens from accepted predictions." }, "audio_tokens": { "type": "integer", "description": "Audio tokens in the completion." }, "image_tokens": { "type": "integer", "description": "Image tokens in the completion." }, "reasoning_tokens": { "type": "integer", "description": "Tokens used for reasoning." }, "rejected_prediction_tokens": { "type": "integer", "description": "Tokens from rejected predictions." }, "text_tokens": { "type": "integer", "description": "Text tokens in the completion." }, "video_tokens": { "type": "integer", "description": "Video tokens in the completion." } } }, "prompt_tokens_details": { "type": "object", "description": "Breakdown of the prompt (input) token count by category.", "properties": { "audio_tokens": { "type": "integer", "description": "Audio tokens in the prompt." }, "cache_creation_input_tokens": { "type": "integer", "description": "Input tokens used to create a cache entry." }, "cache_read_input_tokens": { "type": "integer", "description": "Input tokens read from the cache." }, "cached_tokens": { "type": "integer", "description": "Cached tokens in the prompt." }, "image_tokens": { "type": "integer", "description": "Image tokens in the prompt." }, "text_tokens": { "type": "integer", "description": "Text tokens in the prompt." }, "video_tokens": { "type": "integer", "description": "Video tokens in the prompt." } } } } }, "id": { "type": "string", "description": "Unique identifier for the chat completion." }, "object": { "type": "string", "description": "The object type. Always `chat.completion`." }, "system_fingerprint": { "type": "string", "description": "Backend configuration fingerprint for the model serving the request. May be an empty string." } }, "example": { "choices": [ { "finish_reason": "stop", "index": 0, "message": { "content": "This image is a stylized, pixel-art depiction of a sunset or sunrise over mountains.\n\nHere's a breakdown of what's in the image:\n\n- **The Sun:** A large, pale yellow/cream-colored circle sits just above the mountain ridge, appearing to be setting or rising.\n- **The Mountains:** Two dark purple, jagged peaks form the foreground. The silhouette suggests a simple, stylized mountain range.\n- **The Sky:** The background sky features a gradient of colors, transitioning from deep purple at the top to a warm orange/pink near the horizon where the sun is located.\n\nThe overall aesthetic is minimalist and retro, reminiscent of early video game graphics or digital art with a pixelated style. It evokes a sense of calm and natural beauty through its simple composition.", "role": "assistant" } } ], "conversation": { "id": 1001, "title": "Image content unknown." }, "created": 1736932200, "id": "a1b2c3d4e5f6789012345678901234ab", "model": "qwen/qwen3-vl-8b-instruct", "object": "chat.completion", "system_fingerprint": "", "usage": { "completion_tokens": 159, "completion_tokens_details": { "accepted_prediction_tokens": 0, "audio_tokens": 0, "image_tokens": 0, "reasoning_tokens": 0, "rejected_prediction_tokens": 0, "text_tokens": 159, "video_tokens": 0 }, "prompt_tokens": 93, "prompt_tokens_details": { "audio_tokens": 0, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "cached_tokens": 0, "image_tokens": 79, "text_tokens": 14, "video_tokens": 0 }, "total_tokens": 252 } } } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Not Found" }, "422": { "description": "Validation Error" } }, "summary": "Send message", "tags": [ "Conversations" ] } }, "/conversations/{conversation_id}": { "delete": { "description": "Permanently deletes a conversation thread and all of its messages. This action is irreversible and cannot be undone.", "operationId": "deleteConversation", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "format": "int32", "type": "integer" }, "description": "Unique identifier of the conversation to delete. Use the `id` from [List conversations](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/get-conversations)." } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Conversation deleted successfully" }, "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation that the conversation was deleted." } }, "example": { "message": "Conversation deleted successfully" } } } }, "description": "Conversation deleted successfully" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Not Found" }, "422": { "description": "Validation Error" } }, "summary": "Delete conversation", "tags": [ "Conversations" ] }, "patch": { "tags": [ "Conversations" ], "operationId": "renameConversation", "summary": "Rename conversation", "description": "Rename a conversation that you own. Provide the new title in the request body. Returns the updated conversation.", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "description": "Unique identifier of the conversation to rename. Use the `id` from [List conversations](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/get-conversations).", "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationRenameSchema", "example": { "title": "Describe the attached image" } }, "example": { "title": "Describe the attached image" } } } }, "responses": { "200": { "description": "The conversation was renamed. Returns the updated conversation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation": { "type": "object", "description": "The updated conversation.", "properties": { "id": { "type": "integer", "description": "Unique conversation ID." }, "title": { "type": "string", "description": "Conversation title, generated automatically from the first message and editable via the rename endpoint." }, "base_model_id": { "type": "integer", "description": "ID of the base model used in the conversation." }, "user_id": { "type": "integer", "description": "ID of the user who owns the conversation." }, "organization_id": { "type": "integer", "description": "ID of the organization that owns the conversation." }, "settings": { "type": "object", "description": "Inference settings applied to the conversation, such as temperature or top_p." }, "system_prompt_id": { "type": "integer", "nullable": true, "description": "ID of the saved system prompt applied to the conversation, or null if none." }, "created_at": { "type": "string", "description": "When the conversation was created." }, "modified_at": { "type": "string", "nullable": true, "description": "When the conversation was last updated, or null if it has not changed since creation." }, "is_deleted": { "type": "boolean", "description": "Whether the conversation has been soft-deleted." }, "deleted_at": { "type": "string", "nullable": true, "description": "When the conversation was deleted, or null if it has not been deleted." }, "lorax_model_id": { "type": "integer", "nullable": true, "description": "ID of the LoRA-served fine-tuned model used for the conversation, or null if not applicable." } } } }, "example": { "conversation": { "id": 1001, "title": "Describe the attached image", "base_model_id": 1001, "user_id": 1001, "organization_id": 1001, "settings": {}, "system_prompt_id": null, "created_at": "Wed, 15 Jan 2025 10:30:00 GMT", "modified_at": "Wed, 15 Jan 2025 10:31:00 GMT", "is_deleted": false, "deleted_at": null, "lorax_model_id": null } } }, "example": { "conversation": { "id": 1001, "title": "Describe the attached image", "base_model_id": 1001, "user_id": 1001, "organization_id": 1001, "settings": {}, "system_prompt_id": null, "created_at": "Wed, 15 Jan 2025 10:30:00 GMT", "modified_at": "Wed, 15 Jan 2025 10:31:00 GMT", "is_deleted": false, "deleted_at": null, "lorax_model_id": null } } } } }, "400": { "description": "The request was invalid, for example an empty title.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "404": { "description": "The conversation was not found or is not owned by you.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/conversations/{conversation_id}/messages": { "get": { "description": "Returns the complete message history for the specified conversation thread, ordered chronologically. Each message includes its role, content, and metadata.", "operationId": "getConversationMessages", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "format": "int32", "type": "integer" }, "description": "Unique identifier of the conversation whose messages to retrieve. Use the `id` from [List conversations](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/get-conversations)." } ], "responses": { "200": { "content": { "application/json": { "example": { "messages": [ { "content": "What is in this image?", "image_attachment": { "file_reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "url": "https://your-bucket.s3.amazonaws.com/?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Signature=..." }, "role": "user" } ], "usage": { "completion_tokens": 159, "completion_tokens_details": { "accepted_prediction_tokens": 0, "audio_tokens": 0, "image_tokens": 0, "reasoning_tokens": 0, "rejected_prediction_tokens": 0, "text_tokens": 159, "video_tokens": 0 }, "prompt_tokens": 93, "prompt_tokens_details": { "audio_tokens": 0, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "cached_tokens": 0, "image_tokens": 79, "text_tokens": 14, "video_tokens": 0 }, "total_tokens": 252 } }, "schema": { "type": "object", "properties": { "messages": { "type": "array", "description": "Ordered message history for this conversation.", "items": { "type": "object", "properties": { "content": { "type": "string", "description": "Text content of the message." }, "role": { "type": "string", "description": "Message author role: `user` or `assistant`." }, "image_attachment": { "type": "object", "nullable": true, "description": "Present on a `user` message that was sent with an image, absent otherwise.", "properties": { "file_reference": { "type": "string", "description": "Reference for the attached image, as returned by [Request an image upload URL](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/upload-image)." }, "url": { "type": "string", "description": "A short-lived URL for downloading the attached image." } } } } } }, "usage": { "type": "object", "description": "Aggregate token usage across the conversation.", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" }, "completion_tokens_details": { "type": "object", "description": "Breakdown of the completion (output) token count by category.", "properties": { "accepted_prediction_tokens": { "type": "integer", "description": "Tokens from accepted predictions." }, "audio_tokens": { "type": "integer", "description": "Audio tokens in the completion." }, "image_tokens": { "type": "integer", "description": "Image tokens in the completion." }, "reasoning_tokens": { "type": "integer", "description": "Tokens used for reasoning." }, "rejected_prediction_tokens": { "type": "integer", "description": "Tokens from rejected predictions." }, "text_tokens": { "type": "integer", "description": "Text tokens in the completion." }, "video_tokens": { "type": "integer", "description": "Video tokens in the completion." } } }, "prompt_tokens_details": { "type": "object", "description": "Breakdown of the prompt (input) token count by category.", "properties": { "audio_tokens": { "type": "integer", "description": "Audio tokens in the prompt." }, "cache_creation_input_tokens": { "type": "integer", "description": "Input tokens used to create a cache entry." }, "cache_read_input_tokens": { "type": "integer", "description": "Input tokens read from the cache." }, "cached_tokens": { "type": "integer", "description": "Cached tokens in the prompt." }, "image_tokens": { "type": "integer", "description": "Image tokens in the prompt." }, "text_tokens": { "type": "integer", "description": "Text tokens in the prompt." }, "video_tokens": { "type": "integer", "description": "Video tokens in the prompt." } } } } } }, "example": { "messages": [ { "content": "What is in this image?", "image_attachment": { "file_reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "url": "https://your-bucket.s3.amazonaws.com/?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Signature=..." }, "role": "user" } ], "usage": { "completion_tokens": 159, "completion_tokens_details": { "accepted_prediction_tokens": 0, "audio_tokens": 0, "image_tokens": 0, "reasoning_tokens": 0, "rejected_prediction_tokens": 0, "text_tokens": 159, "video_tokens": 0 }, "prompt_tokens": 93, "prompt_tokens_details": { "audio_tokens": 0, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "cached_tokens": 0, "image_tokens": 79, "text_tokens": 14, "video_tokens": 0 }, "total_tokens": 252 } } } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Not Found" }, "422": { "description": "Validation Error" } }, "summary": "List conversation messages", "tags": [ "Conversations" ] } }, "/models": { "get": { "description": "Returns all models available to the authenticated user in OpenAI-compatible format. Use a model's `id` as the `model` value in inference requests.", "operationId": "getModels", "parameters": [ { "in": "query", "name": "modalities", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ModalityEnum" } }, "description": "Filter models by modality. Repeat the parameter for multiple values, such as `modalities=text-to-image&modalities=image-to-image`." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIModelsListResponseSchema", "example": { "data": [ { "created": 1736932200, "id": "Llama-3.3-70B-Instruct", "object": "model", "owned_by": "hyperstack" } ], "object": "list" } }, "example": { "data": [ { "created": 1736932200, "id": "Llama-3.3-70B-Instruct", "object": "model", "owned_by": "hyperstack" } ], "object": "list" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Bad Request" }, "422": { "description": "Validation Error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Internal Server Error" } }, "summary": "List models", "tags": [ "Models" ] } }, "/models/choices": { "get": { "description": "Returns a simplified list of models available for selection in the AI Studio interface, including display names and base model identifiers. Use this endpoint to populate model picker UI elements.", "operationId": "getModelsChoices", "parameters": [ { "in": "query", "name": "inference", "required": false, "schema": { "type": "boolean", "default": null }, "description": "When `true`, returns only models available for inference." }, { "in": "query", "name": "finetuning", "required": false, "schema": { "type": "boolean", "default": null }, "description": "When `true`, returns only models that support fine-tuning." }, { "in": "query", "name": "modalities", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ModalityEnum" } }, "description": "Filter models by modality. Repeat the parameter for multiple values, such as `modalities=text-to-image&modalities=image-to-image`." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetModelsChoicesResponseSchema", "example": { "models": [ { "base_model_hf_repo": "mistralai/Mistral-Small-24B-Instruct-2501", "display_name": "test-model-123 ", "hf_repo": null, "is_finetuned_model": true, "model_id": 1001, "model_name": "test-model-123 ", "provider": "Hyperstack", "input_modalities": [ "text" ], "output_modalities": [ "text" ], "parameter_schema": null } ], "status": "success" } }, "example": { "models": [ { "base_model_hf_repo": "mistralai/Mistral-Small-24B-Instruct-2501", "display_name": "test-model-123 ", "hf_repo": null, "is_finetuned_model": true, "model_id": 1001, "model_name": "test-model-123 ", "provider": "Hyperstack", "input_modalities": [ "text" ], "output_modalities": [ "text" ], "parameter_schema": null } ], "status": "success" } } }, "description": "OK" }, "422": { "description": "Validation Error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Internal Server Error" } }, "summary": "List model choices", "tags": [ "Models" ] } }, "/org/summary": { "get": { "description": "Returns a high-level summary of resource usage and model activity for the authenticated user's organization, including active model counts, recent training job status, and aggregate token usage.", "operationId": "getOrgSummary", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSummaryResponse", "example": { "status": "success", "summary": { "base_models_count": 60, "datasets_count": 15, "finetuned_models_count": 16, "logs_count": 0 } } }, "example": { "status": "success", "summary": { "base_models_count": 60, "datasets_count": 15, "finetuned_models_count": 16, "logs_count": 0 } } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Not Found" }, "422": { "description": "Validation Error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Internal Server Error" } }, "summary": "Get organization summary", "tags": [ "Overview" ] } }, "/system-prompts": { "get": { "description": "Returns all saved system prompt templates for the authenticated user. System prompts define the assistant's persona, behavior, and response style and can be attached to chat completions or conversation messages.", "operationId": "listSystemPrompts", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemPromptsListSchema", "example": { "prompts": [ { "content": "Updated content for API test. You are a concise assistant.", "created_at": "2025-01-15T10:30:00.000000+00:00", "id": 1001, "name": "example-sysprompt", "organization_id": 1001, "updated_at": "2025-01-15T10:30:00.000000+00:00", "user_id": 1001, "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ] } }, "example": { "prompts": [ { "content": "Updated content for API test. You are a concise assistant.", "created_at": "2025-01-15T10:30:00.000000+00:00", "id": 1001, "name": "example-sysprompt", "organization_id": 1001, "updated_at": "2025-01-15T10:30:00.000000+00:00", "user_id": 1001, "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ] } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Unauthorized" }, "422": { "description": "Validation Error" } }, "summary": "List system prompts", "tags": [ "System Prompts" ] }, "post": { "description": "Creates a new reusable system prompt template. The saved prompt can then be referenced by its ID in chat completion or conversation requests to apply a consistent persona or instruction set without repeating the prompt text.", "operationId": "createSystemPrompt", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemPromptCreateSchema", "example": { "name": "example-sysprompt", "content": "You are a helpful assistant created for API testing purposes." } }, "example": { "name": "example-sysprompt", "content": "You are a helpful assistant created for API testing purposes." } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemPromptResponseSchema", "example": { "content": "You are a helpful assistant created for API testing purposes.", "created_at": "2025-01-15T10:30:00.000000+00:00", "id": 1001, "name": "example-sysprompt", "organization_id": 1001, "updated_at": null, "user_id": 1001, "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, "example": { "content": "You are a helpful assistant created for API testing purposes.", "created_at": "2025-01-15T10:30:00.000000+00:00", "id": 1001, "name": "example-sysprompt", "organization_id": 1001, "updated_at": null, "user_id": 1001, "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Unauthorized" }, "422": { "description": "Validation Error" } }, "summary": "Create system prompt", "tags": [ "System Prompts" ] } }, "/system-prompts/{id}": { "delete": { "description": "Permanently deletes a system prompt template by ID. Existing conversation history that referenced this prompt is unaffected, but the prompt can no longer be attached to new requests.", "operationId": "deleteSystemPrompt", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the system prompt to delete." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessSchema", "example": { "message": "System prompt deleted successfully", "status": "success" } }, "example": { "message": "System prompt deleted successfully", "status": "success" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Not Found" }, "422": { "description": "Validation Error" } }, "summary": "Delete system prompt", "tags": [ "System Prompts" ] }, "get": { "description": "Returns a specific system prompt template by ID, including its name and full content.", "operationId": "getSystemPrompt", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the system prompt to retrieve." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemPromptResponseSchema", "example": { "content": "You are a helpful assistant created for API testing purposes.", "created_at": "2025-01-15T10:30:00.000000+00:00", "id": 1001, "name": "example-sysprompt", "organization_id": 1001, "updated_at": null, "user_id": 1001, "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, "example": { "content": "You are a helpful assistant created for API testing purposes.", "created_at": "2025-01-15T10:30:00.000000+00:00", "id": 1001, "name": "example-sysprompt", "organization_id": 1001, "updated_at": null, "user_id": 1001, "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Not Found" }, "422": { "description": "Validation Error" } }, "summary": "Get system prompt", "tags": [ "System Prompts" ] }, "put": { "description": "Updates the content of an existing system prompt template. Changes take effect immediately for any subsequent requests that reference this prompt ID.", "operationId": "updateSystemPrompt", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the system prompt to update." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemPromptUpdateSchema", "example": { "content": "Updated content for API test. You are a concise assistant." } }, "example": { "content": "Updated content for API test. You are a concise assistant." } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemPromptResponseSchema", "example": { "content": "Updated content for API test. You are a concise assistant.", "created_at": "2025-01-15T10:30:00.000000+00:00", "id": 1001, "name": "example-sysprompt", "organization_id": 1001, "updated_at": "2025-01-15T10:30:00.000000+00:00", "user_id": 1001, "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, "example": { "content": "Updated content for API test. You are a concise assistant.", "created_at": "2025-01-15T10:30:00.000000+00:00", "id": 1001, "name": "example-sysprompt", "organization_id": 1001, "updated_at": "2025-01-15T10:30:00.000000+00:00", "user_id": 1001, "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } }, "description": "Not Found" }, "422": { "description": "Validation Error" } }, "summary": "Update system prompt", "tags": [ "System Prompts" ] } }, "/images/generations": { "post": { "tags": [ "Image Generation" ], "operationId": "generateImageFromText", "summary": "Generate image from text", "description": "Generates one or more images from a text prompt using a text-to-image model. This operation is asynchronous: the response returns a `job_id` with status `queued`. Poll [Get image result](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/get-image-result) until the status is `completed` to retrieve the generated images.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationRequestSchema" }, "example": { "model": "FLUX.1-schnell", "prompt": "A red ceramic coffee mug on a wooden table, soft morning light", "num_images": 1, "image_size": "square_hd" } } } }, "responses": { "200": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageJobAcceptedSchema" }, "example": { "job_id": 256, "status": "queued" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "422": { "description": "Validation Error" } } } }, "/images/edits": { "post": { "tags": [ "Image Generation" ], "operationId": "generateImageFromImage", "summary": "Generate image from image", "description": "Generates an edited image from a source image and a text prompt using an image-to-image model. Supply the source image with `image_url` (an uploaded S3 filename from [Get image upload URL](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/get-image-upload-url), or a reachable URL). This operation is asynchronous: the response returns a `job_id` with status `queued`. Poll [Get image result](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/get-image-result) until the status is `completed` to retrieve the result. Requires an image-to-image model; text-to-image models return a `modality.incompatible` error.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageEditRequestSchema" }, "example": { "model": "FLUX.1-Kontext-dev", "prompt": "Make the background a clear blue sky", "image_url": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "num_images": 1 } } } }, "responses": { "200": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageJobAcceptedSchema" }, "example": { "job_id": 257, "status": "queued" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "422": { "description": "Validation Error" } } } }, "/images/signed-url": { "get": { "tags": [ "Image Generation" ], "operationId": "getImageUploadUrl", "summary": "Get image upload URL", "description": "Returns a presigned S3 URL for uploading a source image. Upload the image bytes with an HTTP PUT to `signed_url`, then pass the returned `filename` as `image_url` in [Generate image from image](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/generate-image-from-image).", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageUploadUrlSchema" }, "example": { "signed_url": "https://ca1-dev.s3.nexgencloud.io/prod-image-bucket-ca1/a1b2c3d4-e5f6-7890-abcd-ef1234567890?X-Amz-Signature=...", "filename": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "422": { "description": "Validation Error" } } } }, "/images/tasks/{job_id}": { "get": { "tags": [ "Image Generation" ], "operationId": "getImageResult", "summary": "Get image result", "description": "Returns the status and progress of an image generation or edit job. While the job runs, `status` is `queued` or `in_progress` with a `progress` percentage. Once `status` is `completed`, the `result` object contains the generated images. Poll this endpoint after submitting a request to [Generate image from text](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/generate-image-from-text) or [Generate image from image](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/generate-image-from-image).", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "type": "integer" }, "description": "The `job_id` returned by [Generate image from text](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/generate-image-from-text) or [Generate image from image](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/generate-image-from-image)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageTaskStatusSchema" }, "example": { "status": "completed", "result": { "created": "2026-01-15T09:30:00.000000", "data": [ { "url": "https://ca1-dev.s3.nexgencloud.io/prod-image-bucket-ca1/a1b2c3d4-e5f6-7890-abcd-ef1234567890.png", "b64_json": null } ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "422": { "description": "Validation Error" } } } }, "/conversations/upload_image": { "get": { "tags": [ "Conversations" ], "operationId": "uploadImage", "summary": "Request an image upload URL", "description": "Request a presigned URL for uploading an image attachment. Upload the image bytes to the returned `signed_url` with an HTTP PUT, then include the returned `file_reference` in a message's `image_attachments`.", "parameters": [ { "in": "query", "name": "content_type", "required": true, "description": "The MIME type of the image you will upload. Supported types: `image/jpeg`, `image/png`, `image/webp`, `image/gif`.", "schema": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp", "image/gif" ] } } ], "responses": { "201": { "description": "Presigned upload details were created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationImageUploadResponseSchema", "example": { "file_reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "signed_url": "https://your-bucket.s3.amazonaws.com/?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Signature=..." } }, "example": { "file_reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "signed_url": "https://your-bucket.s3.amazonaws.com/?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Signature=..." } } } }, "400": { "description": "The request was invalid, for example a missing or unsupported content type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/knowledge-bases": { "get": { "operationId": "listKnowledgeBases", "tags": [ "Knowledge Bases" ], "summary": "List knowledge bases", "description": "Returns your knowledge bases, newest first, with the file and chunk counts for each. Results are paginated.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page of results to return. Defaults to `1`.", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Number of knowledge bases per page. Defaults to `20`.", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Your knowledge bases.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "The knowledge bases on this page.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the knowledge base." }, "uuid": { "type": "string", "description": "Stable string identifier, prefixed with `kb-`." }, "name": { "type": "string", "description": "Name you gave the knowledge base. Unique among your knowledge bases." }, "description": { "type": [ "string", "null" ], "description": "Optional description of what the knowledge base holds." }, "status": { "type": "string", "description": "Current state of the knowledge base.", "enum": [ "active", "processing", "failed", "deleting" ] }, "embedding_model": { "type": "string", "description": "Model used to embed this knowledge base's content." }, "created_at": { "type": "string", "description": "Timestamp when the knowledge base was created.", "format": "date-time" }, "updated_at": { "type": "string", "description": "Timestamp when the knowledge base was last updated.", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the knowledge base was deleted, or `null` if it is active." }, "file_count": { "type": "integer", "description": "Number of files in the knowledge base." }, "chunk_count": { "type": "integer", "description": "Total number of chunks indexed across all files." }, "total_size": { "type": "integer", "description": "Combined size of all files, in bytes." }, "organization_id": { "type": "integer", "description": "Organization that owns the knowledge base." }, "user_id": { "type": "integer", "description": "User who created the knowledge base." } } } }, "page": { "type": "integer", "description": "Current page number." }, "per_page": { "type": "integer", "description": "Number of results per page." }, "total": { "type": "integer", "description": "Total number of knowledge bases." } } }, "example": { "data": [ { "id": 15, "uuid": "kb-696e2cf9-e39e-4b24-b989-8bb75c6c3e6d", "name": "example-knowledge-base", "description": "Reference notes on GPU selection and storage types.", "status": "active", "embedding_model": "BAAI/bge-small-en-v1.5", "ingestion_task_ids": [], "created_at": "2026-07-27T06:39:55.906500Z", "updated_at": "2026-07-27T06:39:55.906500+00:00", "deleted_at": null, "file_count": 2, "chunk_count": 4, "total_size": 1526, "organization_id": 12345, "user_id": 678 } ], "page": 1, "per_page": 20, "total": 1 } } } }, "401": { "description": "Your API key is missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `error` for a failed request." }, "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable description of the error." } } }, "example": { "status": "error", "code": "api_key.invalid", "message": "Your API key is invalid." } } } } } }, "post": { "operationId": "createKnowledgeBase", "tags": [ "Knowledge Bases" ], "summary": "Create a knowledge base", "description": "Creates an empty knowledge base. Add files to it with [**Generate a file upload URL**](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/get-kb-file-upload-url) followed by [**Ingest uploaded files**](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/ingest-kb-files).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Name for the knowledge base. Must be unique among your knowledge bases.", "maxLength": 100 }, "description": { "type": [ "string", "null" ], "maxLength": 500, "description": "Optional description of what the knowledge base holds." } } }, "example": { "name": "example-knowledge-base", "description": "Reference notes on GPU selection and storage types." } } } }, "responses": { "201": { "description": "The knowledge base was created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the knowledge base." }, "uuid": { "type": "string", "description": "Stable string identifier, prefixed with `kb-`." }, "name": { "type": "string", "description": "Name you gave the knowledge base. Unique among your knowledge bases." }, "description": { "type": [ "string", "null" ], "description": "Optional description of what the knowledge base holds." }, "status": { "type": "string", "description": "Current state of the knowledge base.", "enum": [ "active", "processing", "failed", "deleting" ] }, "embedding_model": { "type": "string", "description": "Model used to embed this knowledge base's content." }, "created_at": { "type": "string", "description": "Timestamp when the knowledge base was created.", "format": "date-time" }, "ingestion_task_ids": { "type": "array", "items": { "type": "integer" }, "description": "Ingestion tasks queued for this knowledge base. Empty on creation." } } }, "example": { "id": 15, "uuid": "kb-696e2cf9-e39e-4b24-b989-8bb75c6c3e6d", "name": "example-knowledge-base", "description": "Reference notes on GPU selection and storage types.", "status": "active", "embedding_model": "BAAI/bge-small-en-v1.5", "ingestion_task_ids": [], "created_at": "2026-07-27T06:39:55.906500Z" } } } }, "400": { "description": "You already have a knowledge base with that name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `error` for a failed request." }, "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable description of the error." } } }, "example": { "status": "error", "code": "duplicate_knowledge_base_name", "message": "You already have a knowledge base with this name. Please choose a different name." } } } }, "401": { "description": "Your API key is missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `error` for a failed request." }, "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable description of the error." } } }, "example": { "status": "error", "code": "api_key.invalid", "message": "Your API key is invalid." } } } } } } }, "/knowledge-bases/choices": { "get": { "operationId": "listKnowledgeBaseChoices", "tags": [ "Knowledge Bases" ], "summary": "List selectable knowledge bases", "description": "Returns the ID and name of every knowledge base that has finished indexing, for populating a selector. Knowledge bases that are still processing, failed, or being deleted are excluded.", "responses": { "200": { "description": "Knowledge bases available for selection.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "Selectable knowledge bases.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Numeric ID of the knowledge base." }, "name": { "type": "string", "description": "Name of the knowledge base." } } } } } }, "example": { "data": [ { "id": 15, "name": "example-knowledge-base" } ] } } } }, "401": { "description": "Your API key is missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `error` for a failed request." }, "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable description of the error." } } }, "example": { "status": "error", "code": "api_key.invalid", "message": "Your API key is invalid." } } } } } } }, "/knowledge-bases/{kb_id}": { "get": { "operationId": "getKnowledgeBase", "tags": [ "Knowledge Bases" ], "summary": "Retrieve a knowledge base", "description": "Returns a single knowledge base with its files and a summary of their ingestion states.", "parameters": [ { "name": "kb_id", "in": "path", "required": true, "description": "Numeric ID of the knowledge base. Call the [**List knowledge bases**](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/list-knowledge-bases) API to retrieve the `id` of an existing knowledge base.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The knowledge base.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the knowledge base." }, "uuid": { "type": "string", "description": "Stable string identifier, prefixed with `kb-`." }, "name": { "type": "string", "description": "Name you gave the knowledge base. Unique among your knowledge bases." }, "description": { "type": [ "string", "null" ], "description": "Optional description of what the knowledge base holds." }, "status": { "type": "string", "description": "Current state of the knowledge base.", "enum": [ "active", "processing", "failed", "deleting" ] }, "embedding_model": { "type": "string", "description": "Model used to embed this knowledge base's content." }, "created_at": { "type": "string", "description": "Timestamp when the knowledge base was created.", "format": "date-time" }, "file_count": { "type": "integer", "description": "Number of files in the knowledge base." }, "files": { "type": "array", "description": "Files in the knowledge base.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the file." }, "uuid": { "type": "string", "description": "Stable string identifier, prefixed with `kbf-`." }, "file_name": { "type": "string", "description": "Original filename." }, "mime_type": { "type": "string", "description": "MIME type of the file.", "enum": [ "text/plain", "text/markdown" ] }, "file_size_bytes": { "type": "integer", "description": "Size of the file, in bytes." }, "chunk_count": { "type": "integer", "description": "Number of chunks indexed from this file." }, "chunking_strategy": { "type": "string", "description": "Strategy used to split the file into chunks.", "enum": [ "semantic" ] }, "status": { "type": "string", "description": "Current ingestion state of the file.", "enum": [ "pending", "processing", "indexed", "failed", "cancelled" ] }, "created_at": { "type": "string", "description": "Timestamp when the file was added.", "format": "date-time" } } } }, "ingestion_summary": { "type": "object", "description": "Counts of files in each ingestion state.", "properties": { "pending": { "type": "integer", "description": "Number of files in the `pending` state." }, "processing": { "type": "integer", "description": "Number of files in the `processing` state." }, "completed": { "type": "integer", "description": "Number of files in the `completed` state." }, "failed": { "type": "integer", "description": "Number of files in the `failed` state." }, "cancelled": { "type": "integer", "description": "Number of files in the `cancelled` state." } } }, "ingestion_task_ids": { "type": "array", "items": { "type": "integer" }, "description": "Ingestion tasks currently queued or running." } } }, "example": { "id": 15, "uuid": "kb-696e2cf9-e39e-4b24-b989-8bb75c6c3e6d", "name": "example-knowledge-base", "description": "Reference notes on GPU selection and storage types.", "status": "active", "embedding_model": "BAAI/bge-small-en-v1.5", "ingestion_task_ids": [], "created_at": "2026-07-27T06:39:55.906500Z", "file_count": 2, "files": [ { "id": 24, "uuid": "kbf-55fc6b25-3c9c-4c13-ab52-b030dc392a4e", "file_name": "example-storage-notes.txt", "mime_type": "text/plain", "file_size_bytes": 683, "chunk_count": 2, "chunking_strategy": "semantic", "status": "indexed", "created_at": "2026-07-27T06:43:55.112452Z" } ], "ingestion_summary": { "pending": 0, "processing": 0, "completed": 2, "failed": 0, "cancelled": 0 } } } } }, "401": { "description": "Your API key is missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `error` for a failed request." }, "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable description of the error." } } }, "example": { "status": "error", "code": "api_key.invalid", "message": "Your API key is invalid." } } } }, "404": { "description": "No knowledge base with that ID exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `error` for a failed request." }, "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable description of the error." } } }, "example": { "status": "error", "code": "knowledge_base.not_found", "message": "Knowledge base not found." } } } } } }, "delete": { "operationId": "deleteKnowledgeBase", "tags": [ "Knowledge Bases" ], "summary": "Delete a knowledge base", "description": "Deletes a knowledge base along with its files and everything indexed from them. Any conversation that used it is detached from it. This cannot be undone.", "parameters": [ { "name": "kb_id", "in": "path", "required": true, "description": "Numeric ID of the knowledge base. Call the [**List knowledge bases**](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/list-knowledge-bases) API to retrieve the `id` of an existing knowledge base.", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "The knowledge base was deleted. No content is returned." }, "401": { "description": "Your API key is missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `error` for a failed request." }, "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable description of the error." } } }, "example": { "status": "error", "code": "api_key.invalid", "message": "Your API key is invalid." } } } }, "404": { "description": "No knowledge base with that ID exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `error` for a failed request." }, "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable description of the error." } } }, "example": { "status": "error", "code": "knowledge_base.not_found", "message": "Knowledge base not found." } } } } } } }, "/knowledge-bases/{kb_id}/files/upload-url": { "get": { "operationId": "getKbFileUploadUrl", "tags": [ "Knowledge Bases" ], "summary": "Generate a file upload URL", "description": "Returns a pre-signed URL for uploading one file, along with the storage key you pass to [**Ingest uploaded files**](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/ingest-kb-files). Upload the file to the URL with a `PUT` request before calling that endpoint. The URL is valid for one hour.", "parameters": [ { "name": "kb_id", "in": "path", "required": true, "description": "Numeric ID of the knowledge base. Call the [**List knowledge bases**](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/list-knowledge-bases) API to retrieve the `id` of an existing knowledge base.", "schema": { "type": "integer" } }, { "name": "filename", "in": "query", "required": true, "description": "Name of the file you are uploading.", "schema": { "type": "string" } }, { "name": "mime_type", "in": "query", "required": true, "description": "MIME type of the file. Only `text/plain` and `text/markdown` are accepted.", "schema": { "type": "string", "enum": [ "text/plain", "text/markdown" ] } } ], "responses": { "200": { "description": "The pre-signed upload URL.", "content": { "application/json": { "schema": { "type": "object", "properties": { "signed_url": { "type": "string", "description": "Pre-signed URL to `PUT` the file to. Valid for one hour." }, "s3_key": { "type": "string", "description": "Storage key for the uploaded file. Pass this to the ingest endpoint." } } }, "example": { "signed_url": "https://example-object-storage/preprod-knowledge-base-files-bucket/knowledge-bases/kb-12345/kbf-032d115ac61f49648a0a0c852106757e.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Signature=REDACTED", "s3_key": "knowledge-bases/kb-12345/kbf-032d115ac61f49648a0a0c852106757e.txt" } } } }, "401": { "description": "Your API key is missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `error` for a failed request." }, "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable description of the error." } } }, "example": { "status": "error", "code": "api_key.invalid", "message": "Your API key is invalid." } } } }, "404": { "description": "No knowledge base with that ID exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `error` for a failed request." }, "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable description of the error." } } }, "example": { "status": "error", "code": "knowledge_base.not_found", "message": "Knowledge base not found." } } } }, "422": { "description": "The MIME type is not supported.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `error` for a failed request." }, "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable description of the error." } } }, "example": { "status": "error", "code": "knowledge_base.mime_type.invalid", "message": "mime_type must be one of: text/plain, text/markdown" } } } } } } }, "/knowledge-bases/{kb_id}/files/ingest": { "post": { "operationId": "ingestKbFiles", "tags": [ "Knowledge Bases" ], "summary": "Ingest uploaded files", "description": "Queues one or more uploaded files for indexing. Call this after uploading each file to the pre-signed URL from [**Generate a file upload URL**](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/get-kb-file-upload-url). Indexing runs in the background, so the response returns immediately with a task per file.", "parameters": [ { "name": "kb_id", "in": "path", "required": true, "description": "Numeric ID of the knowledge base. Call the [**List knowledge bases**](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/list-knowledge-bases) API to retrieve the `id` of an existing knowledge base.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "description": "One entry per uploaded file.", "items": { "type": "object", "required": [ "s3_key", "filename", "mime_type", "file_size_bytes" ], "properties": { "s3_key": { "type": "string", "description": "Storage key returned when you generated the upload URL. Call the [**Generate a file upload URL**](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/get-kb-file-upload-url) API to retrieve the `s3_key` for the uploaded file." }, "filename": { "type": "string", "description": "Name of the uploaded file.", "maxLength": 512 }, "mime_type": { "type": "string", "description": "MIME type of the file.", "enum": [ "text/plain", "text/markdown" ] }, "file_size_bytes": { "type": "integer", "description": "Size of the uploaded file, in bytes.", "exclusiveMinimum": 0 }, "chunking_strategy": { "type": "string", "description": "How the file is split into chunks. Defaults to `semantic`.", "enum": [ "semantic" ], "default": "semantic" } } } }, "example": [ { "s3_key": "knowledge-bases/kb-12345/kbf-032d115ac61f49648a0a0c852106757e.txt", "filename": "example-storage-notes.txt", "mime_type": "text/plain", "file_size_bytes": 683, "chunking_strategy": "semantic" } ] } } }, "responses": { "202": { "description": "The files were queued for indexing.", "content": { "application/json": { "schema": { "type": "array", "description": "One entry per queued file.", "items": { "type": "object", "properties": { "file_name": { "type": "string", "description": "Name of the queued file." }, "file_uuid": { "type": "string", "description": "Stable identifier for the new file, prefixed with `kbf-`." }, "ingestion_task_id": { "type": "integer", "description": "ID of the ingestion task. Pass this to the status endpoint." }, "status": { "type": "string", "description": "Initial state of the file.", "enum": [ "pending" ] } } } }, "example": [ { "file_name": "example-storage-notes.txt", "file_uuid": "kbf-55fc6b25-3c9c-4c13-ab52-b030dc392a4e", "ingestion_task_id": 24, "status": "pending" } ] } } }, "401": { "description": "Your API key is missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `error` for a failed request." }, "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable description of the error." } } }, "example": { "status": "error", "code": "api_key.invalid", "message": "Your API key is invalid." } } } }, "404": { "description": "No knowledge base with that ID exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `error` for a failed request." }, "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable description of the error." } } }, "example": { "status": "error", "code": "knowledge_base.not_found", "message": "Knowledge base not found." } } } } } } }, "/knowledge-bases/{kb_id}/files": { "delete": { "operationId": "deleteKnowledgeBaseFiles", "tags": [ "Knowledge Bases" ], "summary": "Remove files from a knowledge base", "description": "Removes one or more files and the chunks indexed from them, so their content stops being retrieved. Cleanup runs in the background. Removing a file that has already been removed succeeds without doing anything.", "parameters": [ { "name": "kb_id", "in": "path", "required": true, "description": "Numeric ID of the knowledge base. Call the [**List knowledge bases**](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/list-knowledge-bases) API to retrieve the `id` of an existing knowledge base.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "file_ids" ], "properties": { "file_ids": { "type": "array", "items": { "type": "integer" }, "description": "IDs of the files to remove. Call the [**Retrieve a knowledge base**](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/get-knowledge-base) API to retrieve the `id` of an existing file." } } }, "example": { "file_ids": [ 24, 25 ] } } } }, "responses": { "202": { "description": "The files were marked for deletion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `success` when the request is accepted." }, "message": { "type": "string", "description": "Confirmation that the files were marked for deletion." } } }, "example": { "status": "success", "message": "Knowledge base files marked for deletion." } } } }, "401": { "description": "Your API key is missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `error` for a failed request." }, "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable description of the error." } } }, "example": { "status": "error", "code": "api_key.invalid", "message": "Your API key is invalid." } } } }, "404": { "description": "No knowledge base with that ID exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `error` for a failed request." }, "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable description of the error." } } }, "example": { "status": "error", "code": "knowledge_base.not_found", "message": "Knowledge base not found." } } } } } } }, "/knowledge-bases/{kb_id}/status": { "get": { "operationId": "getKnowledgeBaseStatus", "tags": [ "Knowledge Bases" ], "summary": "Retrieve ingestion task status", "description": "Returns the state of specific ingestion tasks for a knowledge base. Pass the task IDs returned by [**Ingest uploaded files**](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/ingest-kb-files). To check a whole knowledge base instead, use [**Retrieve status for multiple knowledge bases**](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/post-knowledge-bases-status).", "parameters": [ { "name": "kb_id", "in": "path", "required": true, "description": "Numeric ID of the knowledge base. Call the [**List knowledge bases**](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/list-knowledge-bases) API to retrieve the `id` of an existing knowledge base.", "schema": { "type": "integer" } }, { "name": "task_ids", "in": "query", "required": true, "description": "IDs of the ingestion tasks to check. At least one is required. Call the [**Ingest uploaded files**](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/ingest-kb-files) API to retrieve the `ingestion_task_id` of a queued file.", "schema": { "type": "array", "items": { "type": "integer" } } } ], "responses": { "200": { "description": "The requested ingestion tasks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "State of each requested task.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "ID of the ingestion task." }, "status": { "type": "string", "description": "Current state of the task.", "enum": [ "pending", "processing", "completed", "failed", "cancelled" ] }, "file_name": { "type": "string", "description": "File the task is indexing." } } } } } }, "example": { "data": [ { "id": 24, "status": "completed", "file_name": "example-storage-notes.txt" } ] } } } }, "400": { "description": "No task IDs were supplied.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `error` for a failed request." }, "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable description of the error." } } }, "example": { "status": "error", "code": "knowledge_base.task_ids_required", "message": "At least one knowledge base task id is required." } } } }, "401": { "description": "Your API key is missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `error` for a failed request." }, "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable description of the error." } } }, "example": { "status": "error", "code": "api_key.invalid", "message": "Your API key is invalid." } } } }, "404": { "description": "No knowledge base with that ID exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `error` for a failed request." }, "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable description of the error." } } }, "example": { "status": "error", "code": "knowledge_base.not_found", "message": "Knowledge base not found." } } } } } } }, "/knowledge-bases/status": { "post": { "operationId": "postKnowledgeBasesStatus", "tags": [ "Knowledge Bases" ], "summary": "Retrieve status for multiple knowledge bases", "description": "Returns the current state, counts, and ingestion summary for several knowledge bases in one call. Use this to refresh a list view without polling each knowledge base separately.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kb_ids" ], "properties": { "kb_ids": { "type": "array", "items": { "type": "integer" }, "description": "IDs of the knowledge bases to check. Call the [**List knowledge bases**](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/list-knowledge-bases) API to retrieve the `id` of an existing knowledge base." }, "include_tasks_status": { "type": "boolean", "default": false, "description": "Set to `true` to include per-task detail in `tasks`." }, "task_ids": { "type": "array", "items": { "type": "integer" }, "description": "Optional. Limits `tasks` to these ingestion tasks. Call the [**Ingest uploaded files**](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/ingest-kb-files) API to retrieve the `ingestion_task_id` of a queued file." } } }, "example": { "kb_ids": [ 15, 16 ], "include_tasks_status": true } } } }, "responses": { "200": { "description": "Status for each requested knowledge base.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "Status for each knowledge base that was found.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Numeric ID of the knowledge base." }, "status": { "type": "string", "description": "Current state of the knowledge base.", "enum": [ "active", "processing", "failed", "deleting" ] }, "file_count": { "type": "integer", "description": "Number of files in the knowledge base." }, "chunk_count": { "type": "integer", "description": "Total number of chunks indexed." }, "total_size": { "type": "integer", "description": "Combined size of all files, in bytes." }, "ingestion_summary": { "type": "object", "description": "Counts of files in each ingestion state.", "properties": { "pending": { "type": "integer", "description": "Number of files in the `pending` state." }, "processing": { "type": "integer", "description": "Number of files in the `processing` state." }, "completed": { "type": "integer", "description": "Number of files in the `completed` state." }, "failed": { "type": "integer", "description": "Number of files in the `failed` state." }, "cancelled": { "type": "integer", "description": "Number of files in the `cancelled` state." } } }, "tasks": { "type": "array", "description": "Per-task detail when `include_tasks_status` is `true`.", "items": { "type": "object" } } } } }, "not_found_kb_ids": { "type": "array", "items": { "type": "integer" }, "description": "Requested IDs that do not exist." } } }, "example": { "data": [ { "id": 15, "status": "active", "file_count": 2, "chunk_count": 4, "total_size": 1526, "ingestion_summary": { "pending": 0, "processing": 0, "completed": 2, "failed": 0, "cancelled": 0 }, "tasks": [] } ], "not_found_kb_ids": [] } } } }, "401": { "description": "Your API key is missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `error` for a failed request." }, "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable description of the error." } } }, "example": { "status": "error", "code": "api_key.invalid", "message": "Your API key is invalid." } } } } } } }, "/knowledge-bases/{kb_id}/cancel-ingestion": { "post": { "operationId": "cancelKnowledgeBaseIngestion", "tags": [ "Knowledge Bases" ], "summary": "Cancel knowledge base ingestion", "description": "Stops the ingestion tasks that have not finished for a knowledge base. Chunks already written for those files are discarded, while files that finished indexing keep their chunks and stay searchable. Returns `404` when the knowledge base has no ingestion in progress.", "parameters": [ { "name": "kb_id", "in": "path", "required": true, "description": "Numeric ID of the knowledge base. Call the [**List knowledge bases**](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/list-knowledge-bases) API to retrieve the `id` of an existing knowledge base.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Ingestion was cancelled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `success` when ingestion is cancelled." }, "message": { "type": "string", "description": "Confirmation that ingestion was cancelled." } } }, "example": { "status": "success", "message": "Knowledge base ingestion cancelled." } } } }, "401": { "description": "Your API key is missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `error` for a failed request." }, "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable description of the error." } } }, "example": { "status": "error", "code": "api_key.invalid", "message": "Your API key is invalid." } } } }, "404": { "description": "The knowledge base has no ingestion task in progress.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `error` for a failed request." }, "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable description of the error." } } }, "example": { "status": "error", "code": "knowledge_base_ingestion_task.not_found", "message": "Knowledge base ingestion task not found." } } } } } } } }, "components": { "schemas": { "BaseModelInfoSchema": { "properties": { "available_for_finetuning": { "type": "boolean", "description": "Whether this model can be used for fine-tuning jobs." }, "available_for_inference": { "type": "boolean", "description": "Whether this model can be deployed for inference." }, "default_batch_size": { "type": "integer", "description": "Total batch size used during fine-tuning." }, "default_gradient_accumulation_steps": { "type": "integer", "description": "Number of gradient accumulation steps for fine-tuning." }, "default_lr": { "type": "number", "description": "Learning rate for fine-tuning." }, "default_micro_batch_size": { "type": "integer", "description": "Per-device micro-batch size for fine-tuning." }, "deployment_records": { "items": {}, "type": "array", "description": "List of active deployment records associated with this model." }, "display_name": { "type": "string", "description": "Human-readable name for the model shown in the UI." }, "hf_repo": { "type": "string", "description": "Hugging Face repository identifier for this model." }, "model_id": { "type": "integer", "description": "Unique numeric identifier for the base model." }, "model_name": { "type": "string", "description": "Canonical model identifier used in API requests." }, "model_type": { "type": "string", "description": "Category of model. Common values: `\"language_model\"`, `\"image_model\"`." }, "supported_context_len": { "type": "integer", "description": "Maximum context length (in tokens) supported by this model." }, "supported_locations": { "items": { "type": "string" }, "type": "array", "description": "List of region identifiers where this model is available for deployment." }, "training_time_per_log": { "type": "number", "description": "Estimated training time (in seconds) per log step, used for duration projections." }, "training_time_y_intercept": { "type": "number", "description": "Y-intercept of the training time regression curve, used for fine-tuning duration estimates." }, "allowed_hf_lora_adapter_size": { "type": "integer", "description": "Maximum allowed size (in bytes) for a Hugging Face LoRA adapter when fine-tuning this model." }, "input_token_cost_per_m": { "type": "number", "description": "Cost in USD per million input tokens for inference." }, "is_third_party": { "type": "boolean", "description": "Whether this model was imported by the user (third-party) rather than provided natively by Hyperstack." }, "output_token_cost_per_m": { "type": "number", "description": "Cost in USD per million output tokens for inference." }, "training_cost_per_log": { "type": "number", "description": "Estimated training cost per log step, used for fine-tuning cost projections." }, "input_modalities": { "type": "array", "items": { "type": "string" }, "description": "Input modalities the model accepts, such as `text` and `image`. A model that lists `image` supports image-to-text input." }, "output_modalities": { "type": "array", "items": { "type": "string" }, "description": "Output modalities the model produces, such as `text`." } }, "required": [ "available_for_finetuning", "available_for_inference", "default_batch_size", "default_gradient_accumulation_steps", "default_lr", "default_micro_batch_size", "deployment_records", "display_name", "hf_repo", "model_id", "model_name", "model_type", "supported_context_len", "supported_locations", "training_time_per_log", "training_time_y_intercept" ], "title": "BaseModelInfoSchema", "type": "object" }, "BaseModelsResponseSchema": { "properties": { "models": { "items": { "$ref": "#/components/schemas/BaseModelInfoSchema" }, "type": "array", "description": "List of available base model objects." }, "status": { "default": "success", "type": "string", "description": "Indicates the result of the operation. Typically `\"success\"`." } }, "required": [ "models" ], "title": "BaseModelsResponseSchema", "type": "object" }, "ConversationSendMessageRequestSchema": { "properties": { "message": { "type": "string", "example": "What can you help me with today?", "description": "The user's message text to send to the model." }, "model": { "type": "string", "example": "Llama-3.3-70B-Instruct", "description": "Model to use for this message. Use the `model_name` from [List base models](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/get-base-models) for base models, or the `model_name` from [List owned models](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/get-owned-models) for a deployed fine-tuned model." }, "conversation_id": { "type": "integer", "default": null, "example": 1001, "description": "ID of an existing conversation thread to continue. If null or omitted, a new conversation thread is created and its ID is returned in the response." }, "settings": { "title": "Settings", "type": "object", "description": "Additional inference settings to override for this message (e.g. temperature, top_p)." }, "stream": { "default": false, "type": "boolean", "example": false, "description": "When `true`, returns the response as a stream of server-sent events." }, "stream_options": { "title": "Stream Options", "type": "object", "description": "Options that control streaming behaviour, such as whether to include usage statistics in the final stream chunk." }, "system_prompt_id": { "type": "integer", "default": null, "description": "ID of a saved system prompt template to apply to this message. Create and manage system prompts via [Create system prompt](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/create-system-prompt)." }, "image_attachments": { "items": { "type": "string" }, "maxItems": 1, "type": "array", "default": null, "nullable": true, "description": "Optional image attachment for the message. Use the `file_reference` from [Request an image upload URL](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/upload-image). A maximum of one image is supported per message." }, "knowledge_base_id": { "type": [ "integer", "null" ], "default": null, "description": "Optional. ID of a knowledge base to ground the response in. When set, relevant passages are retrieved and passed to the model, and the response includes a `citations` array naming the sources used." } }, "required": [ "model", "message" ], "title": "ConversationSendMessageRequestSchema", "type": "object", "example": { "model": "Llama-3.3-70B-Instruct", "message": "What did I just say?", "conversation_id": 1001, "stream": false } }, "ErrorSchema": { "properties": { "code": { "default": null, "type": "integer", "description": "HTTP status code associated with the error." }, "message": { "type": "string", "default": null, "description": "Human-readable description of the error." }, "status": { "type": "string", "default": null, "description": "Indicates the result of the operation. Typically `\"error\"` for failed requests." } }, "title": "ErrorSchema", "type": "object" }, "GetModelResponseSchema": { "properties": { "message": { "title": "Message", "type": "object", "description": "Model details object." }, "status": { "default": "success", "type": "string", "description": "Indicates the result of the operation. Typically `\"success\"`." } }, "required": [ "message" ], "title": "GetModelResponseSchema", "type": "object" }, "GetModelsChoicesResponseSchema": { "properties": { "models": { "items": { "$ref": "#/components/schemas/ModelOptionSchema" }, "type": "array", "description": "List of model objects available for inference selection." }, "status": { "default": "success", "type": "string", "description": "Indicates the result of the operation. Typically `\"success\"`." } }, "required": [ "models" ], "title": "GetModelsChoicesResponseSchema", "type": "object" }, "InferenceRequestSchema": { "properties": { "messages": { "items": { "$ref": "#/components/schemas/ChatCompletionMessageSchema" }, "minItems": 1, "type": "array", "description": "Conversation history as an ordered array of messages. Each message has a `role` and `content`. For image-to-text models, `content` may be an array of text and image parts." }, "model": { "type": "string", "example": "Llama-3.3-70B-Instruct", "description": "Model identifier. Use the `model_name` from [List base models](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/get-base-models) for base models, or the `model_name` from [List owned models](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/get-owned-models) for fine-tuned or imported models." }, "stream": { "default": false, "type": "boolean", "example": false, "description": "When `true`, returns the response as a stream of server-sent events, yielding tokens as they are generated. When `false` (default), waits for the full completion before returning." }, "stream_options": { "default": {}, "title": "Stream Options", "type": "object", "description": "Options that control streaming behaviour, such as whether to include token usage in the final stream chunk." }, "max_tokens": { "type": "integer", "description": "Maximum number of tokens to generate. Defaults to the model's maximum if omitted.", "minimum": 1, "maximum": 4095 }, "temperature": { "type": "number", "description": "Sampling temperature controlling randomness. Lower values produce more deterministic output; higher values increase variety.", "minimum": 0, "maximum": 2, "default": 1 }, "top_p": { "type": "number", "description": "Nucleus sampling threshold. Only tokens comprising the top `top_p` probability mass are considered. Set to `null` to disable.", "minimum": 0, "maximum": 1 }, "top_k": { "type": "integer", "description": "Limits sampling to the `top_k` most probable tokens at each step. Set to `-1` to disable.", "minimum": -1, "maximum": 200, "default": -1 }, "presence_penalty": { "type": "number", "description": "Penalizes tokens that have already appeared in the output, encouraging topic variety.", "minimum": -2, "maximum": 2, "default": 0 }, "repetition_penalty": { "type": "number", "description": "Multiplier applied to the logit of previously generated tokens to reduce repetition. Values above `1.0` penalize repeats; values below `1.0` encourage them.", "minimum": 0.01, "maximum": 2, "default": 1 } }, "required": [ "model", "messages" ], "title": "InferenceRequestSchema", "type": "object", "example": { "model": "Llama-3.3-70B-Instruct", "messages": [ { "role": "user", "content": "Reply with exactly: OK" } ], "stream": false } }, "ModelOptionSchema": { "properties": { "display_name": { "type": "string", "description": "User-friendly display name of the model." }, "is_finetuned_model": { "type": "boolean", "description": "When `true`, the model is a fine-tuned model; when `false`, it is a base model." }, "model_id": { "type": "integer", "description": "Unique identifier of the model." }, "model_name": { "type": "string", "description": "Name of the model, used as the `model` value in inference requests." }, "hf_repo": { "type": "string", "default": null, "description": "Hugging Face repository identifier of the base model, if applicable." }, "base_mode_hf_repo": { "type": "string", "default": null, "description": "Hugging Face repository identifier of the underlying base model for a fine-tuned model, if applicable." }, "provider": { "type": "string", "default": null, "description": "Name of the model provider, such as `HuggingFace` or `Hyperstack`." }, "input_modalities": { "type": "array", "items": { "type": "string" }, "default": null, "description": "Input modalities the model accepts, such as `text` or `image`." }, "output_modalities": { "type": "array", "items": { "type": "string" }, "default": null, "description": "Output modalities the model produces, such as `text` or `image`." }, "parameter_schema": { "type": "object", "default": null, "description": "JSON Schema describing the model's accepted generation parameters. Populated for vision (image) models with their image-generation parameters; `null` for text models." }, "base_model_hf_repo": { "type": "string", "description": "Hugging Face repository identifier of the base model." } }, "required": [ "model_id", "model_name", "display_name", "is_finetuned_model" ], "title": "ModelOptionSchema", "type": "object" }, "OpenAIModelSchema": { "description": "Schema for individual model in OpenAI format.", "properties": { "created": { "type": "integer", "description": "Unix timestamp indicating when the model was created." }, "id": { "type": "string", "description": "Identifier of the model, used as the `model` value in inference requests." }, "owned_by": { "type": "string", "description": "Identifier of the owner of the model." }, "object": { "default": "model", "enum": [ "model" ], "type": "string", "description": "Object type, always `\"model\"`." } }, "required": [ "id", "created", "owned_by" ], "title": "OpenAIModelSchema", "type": "object" }, "OpenAIModelsListResponseSchema": { "description": "OpenAI-compliant response schema for GET /api/v1/models.", "properties": { "data": { "items": { "$ref": "#/components/schemas/OpenAIModelSchema" }, "type": "array", "description": "Array of model objects in OpenAI-compatible format." }, "object": { "default": "list", "enum": [ "list" ], "type": "string", "description": "Object type identifier. Always `\"list\"`." } }, "required": [ "data" ], "title": "OpenAIModelsListResponseSchema", "type": "object" }, "OrganizationSummary": { "properties": { "base_models_count": { "type": "integer", "description": "Number of base models available to the organization." }, "datasets_count": { "type": "integer", "description": "Number of datasets created in the organization." }, "finetuned_models_count": { "type": "integer", "description": "Number of fine-tuned models owned by the organization." }, "logs_count": { "type": "integer", "description": "Total number of logs stored in the organization." } }, "required": [ "base_models_count", "finetuned_models_count", "datasets_count", "logs_count" ], "title": "OrganizationSummary", "type": "object" }, "OrganizationSummaryResponse": { "properties": { "summary": { "$ref": "#/components/schemas/OrganizationSummary", "description": "Aggregated counts of the organization's models, datasets, and logs." }, "status": { "default": "success", "type": "string", "description": "Indicates the result of the operation. Typically `\"success\"`." } }, "required": [ "summary" ], "title": "OrganizationSummaryResponse", "type": "object" }, "SuccessSchema": { "properties": { "message": { "default": null, "type": "string", "description": "Human-readable message describing the operation result." }, "status": { "default": "success", "type": "string", "description": "Indicates the result of the operation. Typically `\"success\"`." }, "deleted_count": { "type": "integer", "default": null, "description": "Number of records deleted by the operation." } }, "title": "SuccessSchema", "type": "object" }, "SystemPromptCreateSchema": { "description": "Schema for creating a new system prompt.", "properties": { "content": { "description": "The system prompt text that defines the model's persona, behavior, and response constraints.", "minLength": 1, "type": "string", "example": "You are a helpful assistant that responds concisely and accurately." }, "name": { "description": "Unique display name for the system prompt template.", "maxLength": 255, "minLength": 1, "type": "string", "example": "example-system-prompt" } }, "required": [ "name", "content" ], "title": "SystemPromptCreateSchema", "type": "object", "example": { "name": "example-sysprompt", "content": "You are a helpful assistant created for API testing purposes." } }, "SystemPromptResponseSchema": { "description": "Schema for system prompt response.", "properties": { "content": { "description": "Content of the system prompt.", "type": "string" }, "id": { "description": "Unique identifier of the system prompt.", "type": "integer" }, "name": { "description": "Name of the system prompt.", "type": "string" }, "organization_id": { "description": "ID of the organization.", "type": "integer" }, "user_id": { "description": "ID of the user who created the prompt.", "type": "integer" }, "created_at": { "format": "date-time", "type": "string", "default": null, "description": "ISO 8601 UTC timestamp indicating when the system prompt was created." }, "updated_at": { "format": "date-time", "type": "string", "default": null, "description": "Last update timestamp." }, "uuid": { "type": "string", "default": null, "description": "UUID of the prompt." } }, "required": [ "id", "name", "content", "user_id", "organization_id" ], "title": "SystemPromptResponseSchema", "type": "object" }, "SystemPromptUpdateSchema": { "description": "Schema for updating an existing system prompt.", "properties": { "content": { "minLength": 1, "type": "string", "default": null, "description": "Replacement text for the system prompt. Overwrites the existing content.", "example": "You are a helpful assistant that responds concisely and accurately." }, "name": { "maxLength": 255, "minLength": 1, "type": "string", "default": null, "description": "Name of the system prompt." } }, "title": "SystemPromptUpdateSchema", "type": "object", "example": { "content": "Updated content for API test. You are a concise assistant." } }, "SystemPromptsListSchema": { "description": "Schema for listing system prompts with pagination.", "properties": { "prompts": { "description": "List of system prompts.", "items": { "$ref": "#/components/schemas/SystemPromptResponseSchema" }, "type": "array" } }, "required": [ "prompts" ], "title": "SystemPromptsListSchema", "type": "object" }, "ImageGenerationRequestSchema": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "description": "ID of the text-to-image model to use, such as `FLUX.1-schnell`. Use the `model_name` from [List base models](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/get-base-models); the model must support the `text-to-image` modality." }, "prompt": { "type": "string", "description": "Text description of the image to generate." }, "negative_prompt": { "type": "string", "default": null, "description": "Text describing what to exclude from the generated image." }, "image_size": { "type": "string", "default": "square_hd", "description": "Output image size, as an aspect-ratio preset or an explicit `WIDTHxHEIGHT` value.", "x-enumDescriptions": { "`square_hd`": "Square output, high resolution.", "`square`": "Square output (1:1).", "`portrait_4_3`": "Portrait output, 3:4 aspect ratio.", "`portrait_16_9`": "Portrait output, 9:16 aspect ratio.", "`landscape_4_3`": "Landscape output, 4:3 aspect ratio.", "`landscape_16_9`": "Landscape output, 16:9 aspect ratio." } }, "num_images": { "type": "integer", "default": 1, "description": "Number of images to generate." }, "num_inference_steps": { "type": "integer", "default": null, "description": "Number of denoising steps. Higher values can improve quality at the cost of speed." }, "guidance_scale": { "type": "number", "default": null, "description": "How closely the result follows the prompt. Higher values follow the prompt more strictly." }, "seed": { "type": "integer", "default": null, "description": "Random seed for reproducible results." }, "scheduler": { "type": "string", "default": null, "description": "Sampler or scheduler to use, when supported by the model." }, "output_format": { "type": "string", "enum": [ "png", "jpeg", "webp" ], "default": null, "description": "Format of the returned image.", "x-enumDescriptions": { "`png`": "Returns a lossless PNG image.", "`jpeg`": "Returns a smaller, lossy JPEG image.", "`webp`": "Returns a compact WebP image." } }, "preset": { "type": "string", "default": null, "description": "Named quality or style preset, when supported by the model." } }, "title": "ImageGenerationRequestSchema" }, "ImageEditRequestSchema": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "description": "ID of the image-to-image model to use, such as `FLUX.1-Kontext-dev`. Use the `model_name` from [List base models](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/get-base-models); the model must support the `image-to-image` modality." }, "prompt": { "type": "string", "description": "Text description of the edit to apply to the source image." }, "image_url": { "type": "string", "default": null, "description": "URL or S3 filename of the source image to edit. Pass the `filename` returned by [Get image upload URL](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/get-image-upload-url) after uploading, or a publicly reachable image URL." }, "image_urls": { "type": "array", "items": { "type": "string" }, "default": null, "description": "Multiple source images to edit, as URLs or S3 filenames returned by [Get image upload URL](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/get-image-upload-url). Use instead of `image_url` when the model accepts several inputs." }, "negative_prompt": { "type": "string", "default": null, "description": "Text describing what to exclude from the result." }, "image_size": { "type": "string", "default": "square_hd", "description": "Output image size, as an aspect-ratio preset or an explicit `WIDTHxHEIGHT` value.", "x-enumDescriptions": { "`square_hd`": "Square output, high resolution.", "`square`": "Square output (1:1).", "`portrait_4_3`": "Portrait output, 3:4 aspect ratio.", "`portrait_16_9`": "Portrait output, 9:16 aspect ratio.", "`landscape_4_3`": "Landscape output, 4:3 aspect ratio.", "`landscape_16_9`": "Landscape output, 16:9 aspect ratio." } }, "num_images": { "type": "integer", "default": 1, "description": "Number of images to generate." }, "num_inference_steps": { "type": "integer", "default": null, "description": "Number of denoising steps. Higher values can improve quality at the cost of speed." }, "guidance_scale": { "type": "number", "default": null, "description": "How closely the result follows the prompt. Higher values follow the prompt more strictly." }, "output_format": { "type": "string", "enum": [ "png", "jpeg", "webp" ], "default": null, "description": "Format of the returned image.", "x-enumDescriptions": { "`png`": "Returns a lossless PNG image.", "`jpeg`": "Returns a smaller, lossy JPEG image.", "`webp`": "Returns a compact WebP image." } }, "preset": { "type": "string", "default": null, "description": "Named quality or style preset, when supported by the model." } }, "title": "ImageEditRequestSchema" }, "ImageJobAcceptedSchema": { "type": "object", "properties": { "job_id": { "type": "integer", "description": "Identifier of the asynchronous image job. Poll [Get image result](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/get-image-result) to retrieve the result." }, "status": { "type": "string", "description": "Initial job status, such as `queued`." } }, "title": "ImageJobAcceptedSchema" }, "ImageData": { "type": "object", "properties": { "url": { "type": "string", "default": null, "description": "URL of the generated image. Populated when the output is returned as a URL." }, "b64_json": { "type": "string", "default": null, "description": "Base64-encoded image. Populated instead of `url` when base64 output is requested." } }, "title": "ImageData" }, "ImageTaskResultSchema": { "type": "object", "properties": { "created": { "type": "string", "description": "Timestamp when the result was produced." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ImageData" }, "description": "Generated images." } }, "title": "ImageTaskResultSchema" }, "ImageTaskStatusSchema": { "type": "object", "properties": { "status": { "type": "string", "description": "Job status: `queued` (accepted, not yet started), `in_progress` (generating, see `progress`), `completed` (result available in `result`), or `failed` (generation error)." }, "progress": { "type": "integer", "default": null, "description": "Completion percentage from 0 to 100. Present while the job is in progress." }, "result": { "allOf": [ { "$ref": "#/components/schemas/ImageTaskResultSchema" } ], "default": null, "description": "Generation result. Present once `status` is `completed`." } }, "title": "ImageTaskStatusSchema" }, "ImageUploadUrlSchema": { "type": "object", "required": [ "signed_url", "filename" ], "properties": { "signed_url": { "type": "string", "description": "Presigned S3 URL. Upload the image bytes with an HTTP PUT to this URL." }, "filename": { "type": "string", "description": "S3 key for the uploaded image. Pass this as `image_url` in [Generate image from image](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/generate-image-from-image)." } }, "title": "ImageUploadUrlSchema" }, "ModalityEnum": { "type": "string", "enum": [ "text-to-text", "text-to-image", "image-to-image", "image-to-text" ], "title": "ModalityEnum", "x-enumDescriptions": { "`text-to-text`": "Returns models that generate text from a text prompt ([text-to-text models](https://docs.hyperstack.cloud/docs/ai-studio/models/third-party-hosted-models#text-to-text-models)).", "`text-to-image`": "Returns models that generate images from a text prompt ([text-to-image models](https://docs.hyperstack.cloud/docs/ai-studio/models/third-party-hosted-models#text-to-image-models)).", "`image-to-image`": "Returns models that generate images from a source image and a text prompt ([image-to-image models](https://docs.hyperstack.cloud/docs/ai-studio/models/third-party-hosted-models#image-to-image-models)).", "`image-to-text`": "Returns models that generate text from an image and a text prompt ([image-to-text models](https://docs.hyperstack.cloud/docs/ai-studio/models/third-party-hosted-models#image-to-text-models))." } }, "ChatCompletionMessageSchema": { "properties": { "content": { "type": "array", "nullable": true, "description": "The message content. For image-to-text models, pass an array of content parts, each a `text` part or an `image_url` part (shown below). For plain text-only messages, you can also pass `content` as a single string.", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "image_url" ], "description": "The content part type." }, "text": { "type": "string", "description": "The text of this part. Provide when `type` is `text`." }, "image_url": { "type": "object", "description": "The image for this part. Provide when `type` is `image_url`.", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "The image as a data URI (base64-encoded) or a publicly reachable URL." }, "detail": { "type": "string", "enum": [ "auto", "high", "low" ], "default": "auto", "description": "How much detail the model uses when processing the image." } } } } } }, "role": { "type": "string", "description": "The role of the message author: `system`, `user`, or `assistant`." } }, "required": [ "role" ], "type": "object", "description": "A single chat message. For image-to-text models, `content` may be an array of text and image parts." }, "ConversationRenameSchema": { "properties": { "title": { "maxLength": 255, "type": "string", "description": "The new conversation title. Maximum 255 characters." } }, "required": [ "title" ], "type": "object", "description": "Request body for renaming a conversation." }, "ConversationImageUploadResponseSchema": { "properties": { "file_reference": { "type": "string", "description": "A reference to the uploaded image. Include this in a message's `image_attachments` when calling [Send message](https://docs.hyperstack.cloud/docs/ai-studio-api-reference/send-message)." }, "signed_url": { "type": "string", "description": "A short-lived URL. Upload the image bytes to it with an HTTP PUT before sending the message." } }, "required": [ "signed_url", "file_reference" ], "type": "object", "description": "Presigned upload details for an image attachment." } }, "securitySchemes": { "apiKey": { "type": "apiKey", "name": "api_key", "in": "header", "description": "API-key authentication. Pass your API key as the `api_key` header value (e.g., `api_key: YOUR_API_KEY`, no prefix). [Generate a key in the Hyperstack console](https://console.hyperstack.cloud/api-keys). The key is personal to your user account and works across every environment and region in your organization." } } } }