Skip to content

OmniAI API Reference

Complete API documentation for the OmniAI platform, providing access to state-of-the-art language models and AI capabilities.

Table of Contents

Overview

OmniAI is a powerful artificial intelligence platform that provides state-of-the-art language models and AI capabilities through a simple, developer-friendly API. The platform supports various AI models for different use cases including chat completions, text generation, and image generation.

Key Features

  • Chat Completions: Generate conversational responses with advanced chat models
  • Text Generation: Create high-quality text content for various applications
  • Image Generation: Create images from text prompts using AI models
  • Scalable Infrastructure: Built for enterprise-scale applications with high availability and performance

Getting Started

To get started with OmniAI:

  1. Sign up for an OmniAI account at omniai.ideamart.io
  2. Generate your API key from the dashboard
  3. Make your first API call
  4. Explore our comprehensive documentation

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: app_<keyId>.<keyValue>

Example: 

Authorization: app_1dd4f39c.8bf5e7f2236a4e0caa8780d8313b098d

Base URL

https://api.ideamart.io/omniai/api

Endpoints

Chat Completions

Creates a model response for the given chat conversation.

Endpoint

POST /v1/chat/completions

Full URL: https://api.ideamart.io/omniai/api/v1/chat/completions

Description

Creates a model response for the given chat conversation. Supports various models with different capabilities for text generation, vision, and audio.

Note: Parameter support can differ depending on the model used to generate the response. Different models have different capabilities and supported features.

Request Body Parameters

messages (Required)
  • Type: array
  • Description: A list of messages comprising the conversation so far. Depending on the model you use, different message types (modalities) are supported, like text, images, and audio.

Message Object Structure:

The messages array contains objects with the following structure depending on the role:

Developer Message: - role (string, required): "developer" - content (string or array, required): The contents of the developer message - name (string, optional): An optional name for the participant

User Message: - role (string, required): "user" - content (string or array, required): The contents of the user message - name (string, optional): An optional name for the participant

Assistant Message: - role (string, required): "assistant" - content (string or array, optional): The contents of the assistant message. Required unless tool_calls or function_call is specified - audio (object, optional): Data about a previous audio response from the model - name (string, optional): An optional name for the participant - refusal (string, optional): The refusal message by the assistant - tool_calls (array, optional): The tool calls generated by the model, such as function calls

System Message: - role (string, required): "system" - content (string or array, required): The contents of the system message - name (string, optional): An optional name for the participant

Tool Message: - role (string, required): "tool" - content (string or array, required): The contents of the tool message - tool_call_id (string, required): Tool call that this message is responding to

model (Required)
  • Type: string
  • Description: Model ID used to generate the response. Available models include:
  • claude-sonnet-4 (Claude Sonnet 4)
  • gemini-2.5-flash-lite (Gemini 2.5 Flash Lite)
  • gemini-2.5-pro (Gemini 2.5 Pro)
  • gpt-4o-mini (GPT-4o Mini)

Each model has different capabilities, performance characteristics, and price points.

temperature (Optional)
  • Type: number
  • Description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both.
  • Default: 1
max_completion_tokens (Optional)
  • Type: integer
  • Description: An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens.
tools (Optional)
  • Type: array
  • Description: A list of tools the model may call. You can provide either custom tools or function tools.
response_format (Optional)
  • Type: object
  • Description: The format in which the model output should be returned. Currently only supports string format.
service_tier (Optional)
  • Type: string
  • Description: Specifies the processing type used for serving the request. If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. If set to 'flex' or 'priority', then the request will be processed with the corresponding service tier. When not set, the default behavior is 'auto'. When the service_tier parameter is set, the response body will include the service_tier value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter.
  • Default: auto
frequency_penalty (Optional)
  • Type: number or null
  • Description: Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.
  • Default: 0
logprobs (Optional)
  • Type: boolean or null
  • Description: Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the content of message.
  • Default: false
n (Optional)
  • Type: integer or null
  • Description: How many chat completion choices to generate for each input message. Note that you will be charged based on the number of generated tokens across all of the choices. Keep n as 1 to minimize costs.
  • Default: 1
presence_penalty (Optional)
  • Type: number or null
  • Description: Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.
  • Default: 0
prompt_cache_key (Optional)
  • Type: string
  • Description: Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the user field.
safety_identifier (Optional)
  • Type: string
  • Description: A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. The IDs should be a string that uniquely identifies each user. We recommend hashing their username or email address, in order to avoid sending us any identifying information.
stop (Optional)
  • Type: string / array / null
  • Description: Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence.
  • Default: null
store (Optional)
  • Type: boolean or null
  • Description: Whether or not to store the output of this chat completion request for use in our model distillation or evals products. Supports text and image inputs. Note: image inputs over 8MB will be dropped.
  • Default: false
top_logprobs (Optional)
  • Type: integer
  • Description: An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability.
top_p (Optional)
  • Type: number
  • Description: An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.
  • Default: 1

Request Example

curl -X POST https://api.ideamart.io/omniai/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: app_1dd4f39c.8bf5e7f2236a4e0caa8780d8313b098d" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "system",
        "content": [
          {
            "type": "text",
            "text": "Act as a friendly English-speaking conversation partner. Start a casual conversation with me about anything."
          }
        ]
      },
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Explain megapixels in a picture "
          }
        ]
      }
    ],
    "response_format": {
      "type": "text"
    }
  }'

Response Example

{
  "id": "chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT",
  "object": "chat.completion",
  "created": 1741569952,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I assist you today?",
        "refusal": null,
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 19,
    "completion_tokens": 10,
    "total_tokens": 29,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "service_tier": "default"
}

Image Generation

Creates an image given a text prompt.

Endpoint

POST /v1/images/generations

Full URL: https://api.ideamart.io/omniai/api/v1/images/generations

Description

Creates an image given a text prompt. Supports GPT Image 1 model for high-quality image generation.

Request Body Parameters

prompt (Required)
  • Type: string
  • Description: A text description of the desired image(s). The maximum length is 32000 characters for GPT Image 1.
background (Optional)
  • Type: string or null
  • Description: Allows to set transparency for the background of the generated image(s). This parameter is supported for GPT Image 1. Must be one of transparent, opaque or auto (default value). When auto is used, the model will automatically determine the best background for the image. If transparent, the output format needs to support transparency, so it should be set to either png (default value) or webp.
  • Default: auto
model (Optional)
  • Type: string
  • Description: The model to use for image generation. Use gpt-image-1 for GPT Image 1.
  • Default: gpt-image-1
moderation (Optional)
  • Type: string or null
  • Description: Control the content-moderation level for images generated by GPT Image 1. Must be either low for less restrictive filtering or auto (default value).
  • Default: auto
n (Optional)
  • Type: integer or null
  • Description: The number of images to generate. Must be between 1 and 10.
  • Default: 1
output_compression (Optional)
  • Type: integer or null
  • Description: The compression level (0-100%) for the generated images. This parameter is supported for GPT Image 1 with the webp or jpeg output formats, and defaults to 100.
  • Default: 100
output_format (Optional)
  • Type: string or null
  • Description: The format in which the generated images are returned. This parameter is supported for GPT Image 1. Must be one of png, jpeg, or webp.
  • Default: png
partial_images (Optional)
  • Type: integer
  • Description: The number of partial images to generate. This parameter is used for streaming responses that return partial images. Value must be between 0 and 3. When set to 0, the response will be a single image sent in one streaming event. Note that the final image may be sent before the full number of partial images are generated if the full image is generated more quickly.
  • Default: 0
quality (Optional)
  • Type: string or null
  • Description: The quality of the image that will be generated. auto (default value) will automatically select the best quality. high, medium and low are supported for GPT Image 1.
  • Default: auto
response_format (Optional)
  • Type: string or null
  • Description: The format in which generated images are returned. GPT Image 1 always returns base64-encoded images (b64_json).
  • Default: url
size (Optional)
  • Type: string or null
  • Description: The size of the generated images. Must be one of 1024x1024, 1536x1024 (landscape), 1024x1536 (portrait), or auto (default value) for GPT Image 1.
  • Default: auto
stream (Optional)
  • Type: boolean or null
  • Description: Generate the image in streaming mode. Defaults to false. See the Image generation guide for more information. This parameter is supported for GPT Image 1.
  • Default: false
style (Optional)
  • Type: string or null
  • Description: The style of the generated images. Must be one of vivid or natural. Vivid causes the model to lean towards generating hyper-real and dramatic images. Natural causes the model to produce more natural, less hyper-real looking images.
  • Default: vivid
user (Optional)
  • Type: string
  • Description: A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse.

Request Example

curl https://api.ideamart.io/omniai/api/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: app_1dd4f39c.8bf5e7f2236a4e0caa8780d8313b098d" \
  -d '{
    "model": "gpt-image-1",
    "prompt": "a red apple",
    "n": 1,
    "size": "1024x1024",
    "quality": "low"
  }'

Response Example

{
  "created": 1767763326,
  "background": "opaque",
  "data": [
    {
      "b64_json": "[Base 64 String]"
    }
  ],
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 9,
    "input_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 9
    },
    "output_tokens": 272,
    "total_tokens": 281
  }
}

Error Codes

All errors follow a consistent JSON structure:

{
  "error": {
    "message": "Human-readable error message",
    "type": "Error type or code",
    "param": "Parameter name that caused the error (if applicable)",
    "code": "Error code (for webhook errors)",
    "additional_data": {
      "key": "value"
    }
  }
}

HTTP Status Codes

400 - Bad Request

Invalid request format or malformed request payload. Check your request body and ensure all required fields are provided with valid values.

Common causes: - Invalid JSON - Missing required fields - Invalid parameter values

401 - Unauthorized

Authentication failed. Your API key is either missing, invalid, or expired. Ensure you're including a valid API key in the Authorization header.

Solution: Check your API key format: Bearer YOUR_API_KEY or app_<keyId>.<keyValue>

402 - Payment Required

Insufficient token balance. Please add more tokens to your account to continue using the API.

Solution: Check your account balance and add credits if needed.

403 - Forbidden

You don't have permission to access this resource. This may be due to insufficient account permissions or trying to access a restricted model.

Solution: Contact support if you believe you should have access.

404 - Not Found

Project not found with the provided API key. Verify that your API key is correct and the project exists.

Solution: Double-check your API key format: keyId.keyValue

429 - Too Many Requests

Rate limit exceeded or token quota exceeded. Please wait before making additional requests or check your token balance.

Solution: Rate limits reset every minute. Check the Retry-After header for wait time.

500 - Internal Server Error

An unexpected error occurred on our servers. Please try again later. If the problem persists, contact our support team.

Note: Our team is automatically notified of server errors.

502 - Bad Gateway

Failed to forward request to the LLM provider. This may be due to provider downtime or connectivity issues.

Solution: Try again in a few moments or check provider status.

503 - Service Unavailable

The service is temporarily unavailable due to maintenance or high load. Please try again in a few moments.

Solution: Check our status page for current service status.

Specific Error Codes

PROJECT_NOT_FOUND (404)

Project not found with API key. The provided API key doesn't match any existing project.

PROJECT_INACTIVE (403)

Project is not active. The project exists but its status is not ACTIVE.

INVALID_LLM_CONFIG (400)

Invalid LLM model. The specified model is not configured or allowed for your project.

RATE_LIMIT_EXCEEDED (429)

Rate limit exceeded. Please try again later. Your project has exceeded the allowed number of requests per time period.

TOKEN_QUOTA_EXCEEDED (429)

Token quota exceeded. Please check your token balance. Your project has used up its allocated token quota.

INSUFFICIENT_BALANCE (402)

Insufficient token balance. Please add more tokens to your account. Your current balance is too low to process the request.

FORWARDING_FAILED (502)

Failed to forward webhook request. The request to the LLM provider failed due to connectivity or provider issues.

Error Handling Best Practices

For API Consumers: - Always check the HTTP status code in addition to the error message - Handle rate limiting errors by implementing exponential backoff - Validate API keys before making requests - Check token balance proactively to avoid quota errors - Implement proper error logging for debugging

Rate Limits

Rate limits reset every minute. When you exceed the rate limit, you'll receive a 429 Too Many Requests response. Check the Retry-After header for the recommended wait time before making additional requests.

Support

For additional help: - Visit the OmniAI Portal - Check service status pages: - OpenAI Status - Claude Status - Gemini Status

Changelog

This documentation reflects the current state of the OmniAI API. For the latest updates and changes, please refer to the official documentation at omniai.ideamart.io.

Last updated: 2026-01-13