Skip to main content

Getting started with AICU API

Copy this page into your coding agent. Everything below applies to every endpoint; the per-service pages (Chat, Images, Audio, X reads) only add what is specific to them.

Base URL​

https://api.aicu.ai/v1

The OpenAI-compatible surfaces live under /v1 (chat, audio) and /v2.5 (images, so the OpenAI SDK's images.edit() works by changing only base_url).

Authentication​

Authorization: Bearer aicu_live_xxxxxxxxxxxxxxxx

Issue a key from the dashboard: https://api.aicu.ai/dashboard/keys

  • The server decides the key prefix. aicu_live_ is a production key; aicu_test_ is a self-declared non-production key you may ask for; aicu_beta_ keys belong to the beta programme and expire on the programme's end date (see news).
  • Keys carry scopes (llm, tts, images, x). New keys get every released public scope. Calling an endpoint outside your key's scopes returns 403 with a body of {"error": "API key does not have required scope: <scope>", "required_scope": "<scope>", "current_scopes": [...]}. Note this one does not follow the {error: {code, message}} shape used elsewhere — error is a plain string and there is no code. Branch on required_scope. Add the missing scope with 権限変更 (Change permissions) at dashboard/keys — you do not need to reissue the key.
  • One key reaches every service. There are no per-provider keys to manage.

Credits (prepaid AP)​

  • Usage is paid with AP, a prepaid unit: 1 USD = 10,000 AP. Yen figures shown anywhere are approximate.
  • Only HTTP 200 responses are billed. Errors and cache hits cost nothing. When the balance reaches zero the key stops with 402; nothing is charged automatically unless you turn on auto-recharge.
  • Your first API call grants $10 worth of AP to a new account.
  • Per-model rates are published and revised weekly; increases are announced at least seven days ahead on news. The machine-readable price list is GET /v1/models (also on the pricing page).
  • Reference points: text-to-speech is 200 AP per 1,000 characters; transcription is 3 AP per 10 seconds of audio; image generation is priced per output image by size and quality (see Images).
  • Balance and per-request history: https://api.aicu.ai/dashboard/history

Errors​

Every error uses one envelope:

{ "error": { "code": "insufficient_ap", "message": "Not enough AP." } }
  • code is a fixed English contract — branch on it. message is for humans and follows your account's language.
  • Some errors add fields next to error (for example required_scope and current_scopes on a scope 403).
  • The full list, per status, is in the OpenAPI document: https://api.aicu.ai/openapi.json (components.responses). Common ones:
StatusCodesMeaning
400invalid_json, invalid_parameter, unsupported_parameterThe request body or a parameter is wrong
401unauthorized, api_key_not_found, expiredFix the key
402insufficient_ap, service_budget_exhaustedTop up, or wait for the campaign budget
403forbidden_scope (and card_required from 2026-10-21)Scope or card requirement
422content_moderatedThe provider refused the content
429rate_limited, user_daily_capSlow down or wait for the daily cap to reset
5xxgeneration_failed, internal_errorRetry with backoff

A 403 with Cloudflare's error code: 1010 and no JSON body means no User-Agent header was sent (the default of urllib and similar). Set one.

Rate limits​

60 requests per minute per key by default. Need more for a production workload? Get in touch.

Long-running requests​

Image generation can exceed the 100-second edge limit. The response id (or the X-AICU-Image-Id header when streaming) lets you collect the result later with GET /v1/images/status/{id}. Nothing is lost when the HTTP connection closes.

SDKs​

  • OpenAI SDK: works as is. Set base_url to https://api.aicu.ai/v1 for chat and audio, and to https://api.aicu.ai/v2.5 for images.generate() / images.edit().
  • TypeScript: see TypeScript SDK.
  • Agents: paste a skill URL — https://api.aicu.ai/skills (LLM, TTS, STT, X).

Support​

© 2026 AICU Inc.