CN8 API Documentation

CN8 is a gateway: every AI capability is a service, called through one proxy URL. The gateway handles auth, billing, usage tracking, and rate limiting so you don't have to.

Base URL: https://api.cn8.io. All service calls follow the same pattern: POST (or GET) /v1/proxy/{service-name}. The gateway receives your request, authenticates your API key, checks permissions and credit balance, forwards to the right backend, tracks usage, deducts cost, and returns the result.

The gateway layer

You never integrate with individual AI providers directly. Every capability — chatbot, agent, LLM completion, TTS, dubbing, image generation, studio processing — is a named service on the gateway. Services have a stable name (e.g. core-chat, core-tts, media-image-generate). You call them all the same way; the gateway routes and handles the rest.

• Single proxy URL pattern: /v1/proxy/{service-name}
• Unified auth: one API key, service-level permissions (allowed_services)
• Unified billing: credit balance deducted per request based on usage (tokens, seconds, items)
• Request tracing: every response carries a gateway.request_id
• Sync and async: some services respond immediately; others return a job_id to poll

Sync vs async services

Sync services (LLM completions, chatbot chat, TTS, image generation, text analysis) respond in the same request. Async services (dubbing, video generation) return HTTP 202 immediately with a job_id. You poll GET /v2/jobs/{job_id} until status is completed or failed, then read result_data. If you configure a webhook, the gateway posts the result to your URL when the job finishes.

Service groups and what they do

• Chatbot — create a collection (knowledge base, stored in a closed environment, indexed for RAG), create chatbots with instructions linked to that collection, open conversation sessions; questions are matched via RAG and answered by an LLM; response via REST or SSE.
• Agent — supervisor agent that at each step decides whether to call a sub-agent, use a tool, or respond directly; you define the graph (supervisor + sub-agents + tools), the supervisor orchestrates; suited for customer-facing helper bots, support triage, multi-step workflows.
• LLM — direct chat completion with a model catalog (tiers: budget, standard, premium); send messages, choose model or use default; response includes content, usage (prompt/completion tokens), and cost in USD.
• Dubbing — send a transcription (segments with start, end, text), choose target language, provider, and gender; the service combines segments, keeps timing, and returns a dubbed audio file (async).
• TTS & Voice Clone — text to speech with pre-built voices or cloned voices; persistent clone or instant clone per request.
• Image Generation — text prompt + style preset (e.g. photorealistic, anime, cinematic); service enhances prompt with preset and applies negatives; returns image URL(s); choose aspect ratio, quality, quantity, model tier.
• Video Generation — text to video or image to video; async job.
• Text Analysis — sentiment, emotion, NER, classification, summarization, keywords, QA, embeddings, semantic search, and more.
• Studio — video/audio/image processing: background removal, upscaling, smart reframe, speech clearance, NSFW detection, captioning, segmentation, inpainting, face & privacy blur (image and video).

Media files

Your media files never pass through the API itself. For services that need video, audio, or images, call the upload-media endpoint to get a presigned upload URL, upload your file directly to it, then pass the returned public_url to any service. This keeps media transfers fast and direct.

Credits and billing

Your account has two credit pools: credit_balance (monthly, resets each period) and topup_balance (purchased, never expires). The gateway always deducts from credit_balance first; when it runs out, topup_balance is used. total_balance = credit_balance + topup_balance. Each service call returns its cost in the response. You can set a credit_limit per API key; when exceeded, the key returns 429.

• Billing units differ by service: tokens (LLM, chatbot), seconds (TTS, dubbing), items (image generation, CRUD operations)
• See the Credits section under Account Management for balance, transactions and transfer endpoints
• See the API Keys section for per-key usage history and credit_limit management