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 jobid. You poll GET /v2/jobs/{jobid} 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, denoising, NSFW detection, captioning, segmentation, inpainting.

Media files

The gateway never handles your media files directly. For services that need video, audio, or images, use the upload-media endpoint to get a presigned S3 PUT URL, upload directly to S3, then pass the returned public_url to any service. This keeps media transfers fast and off the gateway.

Credits and billing

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

• GET /v1/credits — current creditbalance, topupbalance, total_balance
• GET /v1/api-keys/{key_id}/usage — usage and limit status for a key
• Billing units differ by service: tokens (LLM, chatbot), seconds (TTS, dubbing), items (image generation, CRUD operations)