---
name: omni
description: Use when building AI agent integrations for multi-model LLM access, content generation (text, image, video, audio), social media publishing and orchestration, or when agents need to interact with global social platforms (X, LinkedIn, YouTube, Instagram, TikTok, Threads). Use for API integration, CLI setup, task automation, and agent-native workflows.
metadata:
    mintlify-proj: omni
    version: "1.0"
---

# OmniMux Skill

## Product summary

OmniMux is an all-in-one API gateway and social media orchestration platform for AI agents. It provides unified access to multiple LLM providers (Claude, GPT, Gemini, Grok, Kimi, DeepSeek, MiniMax, GLM, Doubao), content generation (images, videos, audio, text), social data access (TikTok, Instagram, YouTube, X), and multi-platform publishing. Delivered as REST API, CLI, Agent Skill, and MCP Server. Base URL: `https://api.omnimux.ai` (or `https://api.omnimux.ai/v1` for OpenAI-compatible clients). Console: `omnimux.ai/dashboard`. Authentication uses `sk-` bearer tokens for AI gateway and social data; separate `access_token` + `New-Api-User` header for publishing/user APIs. Pay-per-call pricing with no subscription. Primary docs: https://docs.omnimux.ai

## When to use

- **LLM access**: Agent needs to call multiple model families (Claude, GPT, Gemini, etc.) through a single gateway with unified authentication
- **Content generation**: Agent must create images, videos, audio, or text using various upstream providers
- **Social media publishing**: Agent needs to publish posts, schedule content, or manage accounts across X, LinkedIn, YouTube, Instagram, TikTok, Threads
- **Social data reads**: Agent needs to fetch user profiles, posts, videos, or search results from social platforms
- **File handling**: Agent must upload/download media files (images, video, audio) with automatic expiration and quota management
- **Async task polling**: Agent creates long-running jobs (video generation, etc.) and needs to poll for completion
- **IDE/CLI integration**: Agent runs in Cursor, VS Code, Claude Desktop, or terminal-based tools and needs model configuration
- **Cost tracking**: Agent needs per-call pricing, pre-charge estimates, and usage reporting

## Quick reference

### Authentication & Base URLs

| Surface | Base URL | Auth Header | Use Case |
| --- | --- | --- | --- |
| AI gateway, social data (read) | `https://api.omnimux.ai` or `/v1` | `Authorization: Bearer sk-...` | Chat completions, image/video gen, social reads |
| Publishing, user APIs | `https://omnimux.ai` | `Authorization: Bearer <access_token>` + `New-Api-User: <user_id>` | Create posts, connect accounts, device login |

### Common HTTP Status Codes

| Status | Meaning | Action |
| --- | --- | --- |
| **200** | Success (check `success` field in publishing APIs) | Proceed |
| **400** | Invalid request (missing/unknown model, invalid params) | Fix request body |
| **401** | Missing/invalid Bearer token | Verify `sk-` key or access token |
| **402** | Insufficient quota (pre-consume failed) | Check account balance; do not retry with backoff |
| **403** | Model/group not allowed for this token | Verify token has access to model |
| **429** | Rate limited | Implement exponential backoff |
| **502/503** | Upstream provider error or service unavailable | Retry with backoff |

### Model Families & Endpoints

| Family | Endpoint | Example Models |
| --- | --- | --- |
| **Text (Chat Completions)** | `POST /v1/chat/completions` | `claude-opus-4-6`, `gpt-5.6-terra`, `gemini-3.8-flash`, `grok-3`, `kimi-k3`, `deepseek-v4-pro` |
| **Images** | `POST /v1/images/generations` | `grok-imagine-image`, `nano-banana-pro`, `seedream-5-0-pro`, `qwen-image-3-0` |
| **Video** | `POST /v1/video/generations` | `minimax-h3`, `kling-v3`, `veo-3.1`, `gemini-omni-flash`, `grok-imagine-video` |
| **Audio (TTS)** | `POST /v1/audio/speech` | `gpt-4o-mini-tts`, `seed-audio-1.0`, `index-tts` |
| **Audio (ASR)** | `POST /v1/audio/transcriptions` | `whisper-1`, `doubao-asr` |
| **Audio (Music)** | `POST /v1/video/generations` | `suno`, `suno-sounds` |
| **Social Data (Read)** | `POST /v1/chat/completions` with model | `tiktok-user`, `instagram-posts`, `x-tweet`, `youtube-video` |
| **Publishing** | `POST /api/social/v1/posts` | Create posts (requires access token) |

### File Upload Methods

| Method | Endpoint | Input | Best For |
| --- | --- | --- | --- |
| **Base64** | `POST /api/v1/files/upload/base64` | Base64 string or Data URL | Small files, embedded data |
| **Stream** | `POST /api/v1/files/upload/stream` | Multipart form-data | Large files (up to 100MB) |
| **URL** | `POST /api/v1/files/upload/url` | Public HTTP/HTTPS URL | Remote files, SSRF-protected |

All files auto-expire after 72 hours. Limit: 2,000 active files per user.

### Video/Media Task Polling

```bash
# Create async task
POST /v1/video/generations
{
  "model": "kling-v3",
  "prompt": "...",
  "seconds": 10
}
# Returns: { "task_id": "...", "status": "queued" }

# Poll for completion
GET /v1/video/generations/{task_id}
# Returns: { "status": "completed", "output": { "video_url": "..." } }
```

Status values: `queued`, `in_progress`, `completed`, `failed`

## Decision guidance

### When to use sync vs. async

| Scenario | Use Sync | Use Async |
| --- | --- | --- |
| Text generation, chat | `stream: true` for SSE, or sync response | Not applicable |
| Image generation (small, fast) | Check model docs; some are sync | Most are async |
| Video generation | Not available | Always async; poll `GET /v1/video/generations/{task_id}` |
| Audio generation | Check model; TTS often sync | Music/sound effects are async |

### When to use which text model

| Need | Model | Notes |
| --- | --- | --- |
| Reasoning, complex tasks | `claude-opus-4-6`, `claude-opus-5` | Highest capability |
| Balanced speed/quality | `claude-sonnet-4-6`, `gpt-5.5` | Good for most tasks |
| Fast, cheap | `claude-haiku-4-5`, `gpt-5.4-mini` | Sufficient for simple tasks |
| Coding | `deepseek-v4-pro`, `kimi-k3` | Strong code generation |
| Multimodal (text+image+audio) | `gpt-5.6-terra`, `gemini-3.8-flash` | Support multiple modalities |

### When to use publishing vs. social data read

| Task | Use Publishing API | Use Social Data API |
| --- | --- | --- |
| Fetch user profile, posts, videos | No | Yes (`tiktok-user`, `instagram-posts`, etc.) |
| Create/publish a post | Yes | No |
| Search social platform | No | Yes (`tiktok-search`, `x-search`, etc.) |
| Connect account, manage auth | Yes | No |

## Workflow

### 1. Make your first API call (text generation)

1. **Get API key**: Sign in to `omnimux.ai/dashboard` → Tokens / API Keys → Create key (looks like `sk-...`)
2. **Set base URL**: Use `https://api.omnimux.ai/v1` for OpenAI-compatible SDKs
3. **Check available models**: `GET /v1/models` or console
4. **Send request**:
   ```bash
   curl https://api.omnimux.ai/v1/chat/completions \
     -H "Authorization: Bearer sk-..." \
     -H "Content-Type: application/json" \
     -d '{
       "model": "claude-opus-4-6",
       "messages": [{"role": "user", "content": "Hello"}]
     }'
   ```
5. **Verify response**: Check `choices[0].message.content` and `usage` fields

### 2. Generate images or video

1. **Choose model**: Check docs for sync vs. async (most are async)
2. **Create task**:
   ```bash
   POST /v1/images/generations  # or /v1/video/generations
   {
     "model": "grok-imagine-image",
     "prompt": "...",
     "n": 1
   }
   ```
3. **For async (video)**: Extract `task_id` from response
4. **Poll for completion**: `GET /v1/video/generations/{task_id}` every 5-10 seconds
5. **Retrieve result**: Extract URL from `output` field when `status: completed`
6. **Persist URLs immediately**: Upstream links may expire

### 3. Upload and use media files

1. **Choose upload method**: Base64 (small), Stream (large), or URL (remote)
2. **Upload**:
   ```bash
   POST /api/v1/files/upload/base64
   {
     "base64_data": "data:image/png;base64,...",
     "file_name": "avatar.png"
   }
   ```
3. **Extract `file_id`** from response (e.g., `file_8e6d425c0e564bde`)
4. **Use in requests**: Pass `file_id` or `file_url` to image/video models
5. **Download**: `GET /api/v1/files/download/{file_id}` (auto-redirects to CDN)

### 4. Publish to social media

1. **Get user access token**: Call `POST /api/user/device/code` → open browser → approve → poll `POST /api/user/device/token`
2. **Connect account**: `POST /api/social/v1/connect` with `provider` (tiktok_direct or zernio) and `platform`
3. **Create post**: `POST /api/social/v1/posts` with `provider`, `account_ids`, `content`, `media_items`
4. **Use correct auth**: Access token + `New-Api-User` header (not `sk-` key)
5. **Check response**: Inspect both HTTP status and `success` field (some errors return 200 with `success: false`)

### 5. Read social data (profiles, posts, videos)

1. **Use Chat Completions endpoint**: `POST /v1/chat/completions` with `sk-` key
2. **Set model**: `tiktok-user`, `instagram-posts`, `x-tweet`, `youtube-video`, etc.
3. **Pass business params**: Top-level body fields (e.g., `username`, `video_id`)
4. **Messages can be dummy**: e.g., `"messages": [{"role": "user", "content": "."}]`
5. **Parse response**: Extract data from `choices[0].message.content`

## Common gotchas

- **Wrong base URL**: Publishing/user APIs use `https://omnimux.ai` (no `/v1`); AI gateway uses `https://api.omnimux.ai/v1`. Do not mix credential surfaces.
- **402 is not a retry**: Insufficient quota (402) is terminal. Check balance before retrying; do not treat as temporary rate limiting.
- **Streaming still charges**: Setting `stream: true` improves UX but billing follows live settlement. Aborting early does not prevent charges.
- **Video polling endpoint**: Use `GET /v1/video/generations/{task_id}` only. Do not use `/v1/videos/{id}` or `/content` (OpenAI Videos API paths).
- **Publishing requires access token**: Use `Authorization: Bearer <access_token>` + `New-Api-User` header, not `sk-` key. Mixing them returns 401.
- **Social data is read-only**: Model IDs like `tiktok-user` fetch data; they do not publish. Use `/api/social/v1/posts` to publish.
- **Files expire after 72 hours**: Do not rely on file URLs for long-term storage. Download or re-upload before expiration.
- **Async tasks need polling**: Image/video generation returns `task_id` immediately. Poll status until `completed` or `failed`; do not assume instant completion.
- **Idempotency key for publishing**: Include `Idempotency-Key` header in post creation to prevent duplicates on retry.
- **Check `success` field in publishing**: HTTP 200 may return `success: false` with upstream errors. Always inspect the `success` field.
- **Model IDs change**: Confirm available models with `GET /v1/models` or console; do not hardcode model names.
- **Bearer token format**: Use `Authorization: Bearer sk-...` (with space). Missing `Bearer` prefix returns 401.

## Verification checklist

Before submitting work with OmniMux:

- [ ] API key is stored server-side only (not in frontend code or public repos)
- [ ] Base URL matches the surface: `https://api.omnimux.ai/v1` for AI gateway, `https://omnimux.ai` for publishing
- [ ] Authorization header includes `Bearer` prefix: `Authorization: Bearer sk-...`
- [ ] Model ID is confirmed available (check console or `GET /v1/models`)
- [ ] For async tasks (video, music), polling loop handles `queued`, `in_progress`, `completed`, `failed` states
- [ ] For publishing, using access token + `New-Api-User` header (not `sk-` key)
- [ ] File uploads include `file_name` or rely on auto-generation; files will expire after 72 hours
- [ ] 402 errors are handled as terminal quota failures (check balance, do not retry with backoff)
- [ ] Streaming requests (`stream: true`) are understood to still incur full charges
- [ ] Social data reads use Chat Completions endpoint with model like `tiktok-user`, not publishing API
- [ ] Response parsing checks both HTTP status and `success` field (especially for publishing)
- [ ] Idempotency keys are included for publishing to prevent duplicate posts on retry

## Resources

- **Comprehensive page index**: https://docs.omnimux.ai/llms.txt
- **API Reference (Text Models)**: https://docs.omnimux.ai/en/api-reference/text-series/claude/complete
- **Connection & Usage (Base URLs, Auth, Error Codes)**: https://docs.omnimux.ai/en/faqs/connection-usage
- **Publishing & Social Media**: https://docs.omnimux.ai/en/api-reference/publishing/create-post

---

> For additional documentation and navigation, see: https://docs.omnimux.ai/llms.txt