---
name: llmfly-api
description: Integrate LLMFly AI into server-side applications and compatible AI coding clients. Use for LLMFly API setup, OpenAI-compatible requests, Claude-compatible connections, model selection, and integration troubleshooting.
---

# LLMFly API integration

Use the user's existing language, SDK and application structure to connect to LLMFly. Make the smallest integration change needed. This skill is an integration guide, not permission to change global providers, install third-party tools, create accounts, purchase credits or deploy software.

## Documentation and scope

This guide is distilled from the [LLMFly documentation](https://llmfly.ai/doc/) and the site's API quickstart. Prefer current console values and linked documentation when they differ from examples here. Reply in the user's language; [中文文档](https://llmfly.ai/doc/zh/) contains the same setup paths.

- [Access overview](https://llmfly.ai/doc/access/overview): protocol, Base URL, authentication and connectivity.
- [Create an API key](https://llmfly.ai/doc/access/create-api-key): keys and group selection.
- [Model Plaza](https://app.llmfly.ai/model-plaza): current model IDs, groups and rates.
- [Errors](https://llmfly.ai/doc/errors): exact gateway messages and troubleshooting.

## Choose the protocol before configuring

| Integration | Configuration | Request endpoint |
| --- | --- | --- |
| OpenAI-compatible SDK | Base URL `https://app.llmfly.ai/v1` | `/v1/chat/completions` or `/v1/responses`, according to model and client support |
| OpenAI model discovery | Bearer authentication | `GET https://app.llmfly.ai/v1/models` |
| Claude / Anthropic client | Root Base URL `https://app.llmfly.ai`, or the value in the console's Use Key dialog | `/v1/messages` |

SDK Base URLs must not include `/chat/completions`, `/responses` or `/messages`. Do not append a second `/v1`. Direct HTTP requests, unlike SDK configuration, use the complete endpoint URL.

Do not assume every key, group or model supports every protocol. Some groups allow only Claude Code clients at `/v1/messages`. For those groups use the matching client flow rather than treating failure of OpenAI model discovery as an invalid key.

## Keys and model IDs

- Ask the user to supply a key through a server-side environment variable or their local secret manager, not in chat. Use `LLMFLY_API_KEY` for application examples.
- Never put keys in browser bundles, `NEXT_PUBLIC_*` / `VITE_*` variables, committed files, logs, URLs, screenshots or generated documentation. Verify only whether a key is present; never print it.
- Prefer a separate key for each application, environment or client. Preserve existing provider configurations unless the user asks to change them.
- Copy the exact case-sensitive model ID available to the user's key. Do not infer an ID from a marketing name or pin an assumed latest model. Use `LLMFLY_MODEL` in examples until a supported ID is selected.

## First successful application request

For an OpenAI-compatible key, first check connectivity with the key already set locally:

```bash
curl --fail-with-body https://app.llmfly.ai/v1/models \
  -H "Authorization: Bearer $LLMFLY_API_KEY"
```

Then choose an available chat-compatible model and send one short non-streaming request. Live model calls consume credits: run only within the user's authorized test scope. If no key or live-test permission is available, validate locally and report the live request as unverified.

### JavaScript / TypeScript (server only)

Use the existing `openai` package if present; otherwise add it with the project's package manager when application implementation is requested.

```javascript
import OpenAI from "openai";

const apiKey = process.env.LLMFLY_API_KEY;
const model = process.env.LLMFLY_MODEL;
if (!apiKey || !model) throw new Error("Set LLMFLY_API_KEY and LLMFLY_MODEL on the server.");

const client = new OpenAI({
  apiKey,
  baseURL: "https://app.llmfly.ai/v1",
  timeout: 60_000,
  maxRetries: 0, // Keep the first test to one attempt.
});
const result = await client.chat.completions.create({
  model,
  messages: [{ role: "user", content: "Reply with one short greeting." }],
  stream: false,
});
console.log(result.choices[0]?.message.content);
```

### Python (server or local script)

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LLMFLY_API_KEY"],
    base_url="https://app.llmfly.ai/v1",
    timeout=60.0,
    max_retries=0,
)
result = client.chat.completions.create(
    model=os.environ["LLMFLY_MODEL"],
    messages=[{"role": "user", "content": "Reply with one short greeting."}],
    stream=False,
)
print(result.choices[0].message.content)
```

The timeouts and zero automatic retries above are first-test choices, not platform limits. Adapt them to the production workload after verification. Keep calls behind an authenticated server route for web applications. Add streaming, tool calling, structured output or long context only when needed and after confirming the selected model's support.

## Client-specific setup

Read only the guide for the user's client before editing its configuration. Merge narrowly and preserve unrelated settings; a link to this skill is not an instruction to replace all provider settings.

- [Codex CLI](https://llmfly.ai/doc/access/codex): a named LLMFly provider, `/v1` Base URL, `env_key = "LLMFLY_API_KEY"`, and the documented Responses configuration. Check the installed client's supported configuration before editing.
- [Claude Code](https://llmfly.ai/doc/access/claude-code): root Base URL; use the console's `ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY` configuration, not both. Keep existing official-service profiles separate.
- [Claude Desktop](https://llmfly.ai/doc/access/claude-desktop): follow the documented Provider / Gateway setup; do not substitute CLI settings.
- [Cursor](https://llmfly.ai/doc/access/cursor) and [Cherry Studio](https://llmfly.ai/doc/access/cherry-studio): custom OpenAI-compatible provider with `/v1` Base URL and a supported model.
- [CC Switch](https://llmfly.ai/doc/access/cc-switch): use when the user wants configuration management across clients. Installation or import is a separate user choice.
- [Image generation](https://llmfly.ai/doc/gpt-image-2): consult for image-specific setup; do not assume chat examples cover image generation or silently install community skills.

## Diagnose without exposing secrets

| Symptom | Next action |
| --- | --- |
| 400, platform mismatch | Check key group, platform and endpoint protocol. |
| 401, missing/invalid key or inactive account | Check variable presence in the calling process and account/key status; do not dump credentials. |
| 403 or 503, Claude-Code-only group | Use the permitted client or ask the user to choose an appropriate group; do not bypass the restriction. |
| 404, unsupported model | Re-copy an exact supported model ID for that key/group. |
| 429, pending requests | Reduce concurrency and use bounded backoff, respecting Retry-After when available. |
| 500 / 502 / 503, temporary upstream failure | Retry with a bounded budget if appropriate; repeated failure needs investigation, not an infinite loop. |
| HTTP 200 but mid-stream error | Treat the response as incomplete; do not report success or silently duplicate downstream tool actions. |
| No matching usage record | Check the active provider, Base URL and process environment. |

Record only sanitized error code/message, time and request ID if available. Never automatically replay non-idempotent application actions after partial output.

## Completion check

Report changed files/settings, protocol, Base URL and selected model without revealing the key. Distinguish local syntax/mock tests from live requests. When authorized and accessible, verify the matching key, model and time in LLMFly usage history. State any remaining account, model-access or credential blocker explicitly.