GPT88 Agent Docs

Complete Integration Guide

Run the full gpt88.cc integration path from API key creation and Base URL selection to client setup, usage checks, and troubleshooting.

What this guide solves

Most failed integrations are not caused by the model itself. They come from mismatched Base URL shape, wrong environment variables, incorrect API key permissions, or missing usage / rate-limit checks. This page connects those steps into one working path: make one request succeed first, then tune the client.

Finish the first integration in 5 steps

integration-flowtext
1. Sign in to the gpt88.cc console
2. Create one API key and store the full value immediately
3. Choose the protocol style: OpenAI compatible / Claude compatible / native Gemini image API
4. Fill in Base URL, API key, and default model in your tool
5. Send one minimal request, then verify usage and billing in the console

The fastest validation path is still one minimal cURL request. If cURL succeeds, your key, balance, model, and route are usually fine. If a client still fails, debug the client config next.

smoke-test.shbash
export GPT88_API_KEY="sk-your-gpt88-api-key"

curl https://api.gpt88.cc/v1/chat/completions \
  -H "Authorization: Bearer $GPT88_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-haiku-4-5-20251001",
    "messages": [
      {"role": "user", "content": "Introduce gpt88.cc in one sentence"}
    ]
  }'

Base URL rules

Decide based on the client protocol, not only on the model family name.

base-url-rulestext
OpenAI-compatible tools
  Base URL: https://api.gpt88.cc
  Typical tools: OpenAI SDK, Codex CLI, Cursor, OpenCode, cURL

Claude / Anthropic-compatible tools
  Base URL: https://api.gpt88.cc
  Typical tools: Claude Code, Anthropic SDK, OpenClaw

Google / Gemini image generation
  Base URL: https://img.gpt88.cc
  Endpoint: /v1beta/models/{MODEL}:generateContent

Use the standard API URL for normal APIs and the media URL for image/video requests; protocol differences are handled by endpoint paths and request formats

Client-specific setup

The shortest mental model is simple: OpenAI-style tools usually need /v1; Claude-style tools usually do not.

Codex CLI

Codex CLI is an OpenAI-style client. Give it a dedicated key and a separate budget where possible.

~/.codex/config.tomltoml
model_provider = "OpenAI"
model = "gpt-5.5"
review_model = "gpt-5.5"
model_reasoning_effort = "high"

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://api.gpt88.cc"
wire_api = "responses"
requires_openai_auth = true
openai-envbash
export OPENAI_API_KEY="$GPT88_API_KEY"
export OPENAI_BASE_URL="https://api.gpt88.cc"

Claude Code

Claude Code follows the Anthropic-style path with https://api.gpt88.cc. Usehttps://img.gpt88.cc for image and video requests.

~/.claude/settings.jsonjson
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.gpt88.cc",
    "ANTHROPIC_AUTH_TOKEN": "your gpt88.cc API key",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
  }
}
anthropic-envbash
export ANTHROPIC_AUTH_TOKEN="$GPT88_API_KEY"
export ANTHROPIC_BASE_URL="https://api.gpt88.cc"
export ANTHROPIC_API_KEY="$GPT88_API_KEY"

OpenAI SDK / Cursor / OpenCode

These clients usually only need two fields changed: base_url and api_key. If the client supports a custom OpenAI provider, choose the OpenAI-compatible option directly.

For full runnable examples, continue with Python SDK and Node.js SDK.

Usage and cost checks

After the first working request, go to the console and verify what really happened: which model was used, how many tokens were counted, which API key made the call, and whether the deduction matches your expectation.

usage-checklisttext
When one request looks too expensive, check in this order:

1. Model choice: did you use a more expensive model than intended?
2. Input tokens: long chats, code context, and tool results inflate prompts quickly
3. Output tokens: longer responses cost more
4. API type: image, audio, and video are not always pure token billing
5. API key: did one client or script loop unexpectedly?
6. request_id: always keep it if support needs to investigate

Common error quick reference

error-quick-referencetext
401 invalid_api_key
  Check Bearer auth format, key completeness, and whether it is a real gpt88.cc key.

403 permission_denied
  The current key does not have access to the model or endpoint.

429 rate_limit_exceeded
  Lower concurrency and retry according to Retry-After or retry_after_seconds.

429 insufficient_quota
  Balance or quota is exhausted.

404 model_not_found
  The model name is wrong or unavailable. Refresh with GET /v1/models.

413 payload_too_large
  Reduce payload size, shorten message history, or compress the image.

503 service_unavailable / upstream_error
  Retry with backoff or switch model / route if necessary.

Slow requests
  Separate network latency, model latency, long context, and slow first-token delay.

For full HTTP and business error mappings, see Error Codes.

Best practices before production

  • Use separate API keys for production, staging, and local development.
  • Name keys by purpose, such as codex-macbook or web-prod.
  • Keep keys only in server-side environment variables or secret managers.
  • Set daily limits, concurrency controls, and alerting before production rollout.
  • Log request_id server-side for future debugging.
  • Refresh model lists from GET /v1/models instead of hardcoding assumptions forever.

Next steps