> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deepshi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> The Deepshi API is an OpenAI-compatible gateway. Base URL: https://api.deepshi.ai/v1. API keys start with sk-bf- and go in the Authorization: Bearer header. Prefer the official OpenAI SDKs pointed at the Deepshi base URL. Model ids are clean with no provider prefix (e.g. deepshi-3.0, claude-opus-4.8, gpt-5.5). Chat and image requests are synchronous; video and music requests are asynchronous job APIs (create, then poll). Every synchronous response carries usage.cost.total_cost in USD. Do not reference the internal /api/* admin plane or virtual keys.

# AGENTS

# Documentation project instructions

## About this project

* These are the public developer docs for the **Deepshi API** — an OpenAI-compatible gateway that gives developers access to Deepshi's models and third-party models via a single API.
* Built on [Mintlify](https://mintlify.com). Pages are MDX files with YAML frontmatter. Configuration lives in `docs.json`.
* The gateway is based on Bifrost. Source lives in `../deepshi-api`. The public product site is [deepshi.ai](https://deepshi.ai/).
* Use the Mintlify MCP server `https://mcp.mintlify.com` to edit content/settings, and `https://www.mintlify.com/docs/mcp` to query Mintlify usage.

## Audience & scope

* **Audience:** developers consuming the API. They get an `sk-bf-...` key from the deepshi.ai dashboard and call the OpenAI-compatible `/v1/*` endpoints.
* **In scope:** the `/v1/*` inference endpoints, authentication with API keys, models, credits/pricing, errors, SDK usage.
* **Out of scope (do NOT document):** the admin/management plane (`/api/*`), virtual-key minting, customer/budget governance, reconcile crons, Modal/Supabase deployment, and any internal infra. Those are Deepshi's own backend integration, not for API customers.

## Terminology

* "API key" / "key" — the user's `sk-bf-...` secret. Don't call it a "virtual key" (that's internal terminology).
* "credits" / "balance" — the user's prepaid USD balance. Don't expose "customer", "wallet", or "budget" internals.
* "model id" — the value of the `model` field, taken from `GET /v1/models`. IDs are clean (no provider prefix): `gpt-4o`, `claude-opus-4.8`, `deepshi-3.0`, etc. — NOT `openai/...`.
* **Documented endpoints:** `GET /v1/models`, `POST /v1/chat/completions`, the image endpoints `POST /v1/images/generations` and `POST /v1/images/edits`, the video endpoints `POST /v1/videos`, `GET /v1/videos/{id}`, `GET /v1/videos/{id}/content`, and `DELETE /v1/videos/{id}`, and the music endpoints `POST /v1/audio/generations`, `GET /v1/audio/generations/{id}`, and `GET /v1/audio/generations/{id}/content`. Still NOT exposed: speech/transcription audio, embeddings, and `/v1/completions`. Source of truth: `deepshi-api/docs/deployment-guides/api_docs.md` and `models.md`.
* **Video models** use an asynchronous job API: create a job (`POST /v1/videos`), poll it (`GET /v1/videos/{id}`) until `status` is `completed`, then read `videos[].url` or follow the `/content` 302 redirect. Beyond `model` and `prompt`, they take model-specific params (`resolution`, `duration`, `aspect_ratio`, `generate_audio`, `input_reference` for image-to-video) discovered via `GET /v1/models`. Pricing is per second of output, billed once on completion; unlike chat/image, video responses do NOT carry an inline `usage.cost`. Video ids are per-key. See `capabilities/video-generation.mdx` and `models/video-models.mdx`.
* **Music (audio) models** use an asynchronous job API: create a job (`POST /v1/audio/generations`), poll it (`GET /v1/audio/generations/{id}`) until `status` is `completed`, then read `audio[].url` or follow the `/content` 302 redirect. There is no delete/cancel endpoint (unlike video). The launch model is `minimax-music-v2` (MiniMax Music 2.0): it takes a style `prompt` (≤300 chars) plus a required `lyrics_prompt` (10–3000 chars, `[Verse]`/`[Chorus]` tags) and generates a vocal song — it does NOT do instrumental-only output. Optional output params (`sample_rate`, `bitrate`, `format` — mp3 only) come from `GET /v1/models` (the `parameters` object). Create returns `status: "in_progress"` (no `size`/`seconds`); the completed poll adds `audio[]`, `seconds` (string), and `completed_at`. Pricing is flat per track, billed once on completion; like video, responses do NOT carry an inline `usage.cost`. Audio ids are per-key. See `capabilities/audio-generation.mdx` and `models/audio-models.mdx`.
* **Image models** use a fixed request schema (standard fields) plus model-specific sizing/quality params (`width`/`height`, `aspect_ratio`, `resolution`, `quality`, `image_size`) that vary by model — callers discover them via `GET /v1/models` (the `parameters` object, plus the top-level `edit`, `prompt_max_length`, and modality fields). Pricing is NOT in `/v1/models`; image pricing is per-image and tier-aware (often `resolution` × `quality`), shown on deepshi.ai, and every response returns the actual `usage.cost`. Responses do not expose the internal `deepshi_resolved` echo. See `capabilities/image-generation.mdx`.
* Deepshi's own models: **Deepshi 2.0** (`deepshi-2.0`, largely uncensored; no tools/reasoning/json) and **Deepshi 3.0** (`deepshi-3.0`, multimodal flagship; tools, reasoning, json, logprobs). Do NOT use old "Flow/Forge" or "R1/R2" names.
* Default example model in docs: `deepshi-3.0` (supports all features). Mention `deepshi-2.0` as the uncensored option.
* Frontier text models (clean ids): `claude-opus-4.8/4.7`, `claude-sonnet-4.6`, `gpt-5.5/5.4/4.1/4o`, `gemini-3.5-flash`, `grok-4.3/4.20`, `glm-5.2/5.1/5`, `kimi-k2.6`, `gemma-4-31b-it`.
* Pricing is **USD per 1M tokens**. Every response carries `usage.cost.total_cost` (Deepshi extension, USD).
* Reasoning: control it with the `reasoning_effort` request param (`none`/`low`/`medium`/`high`; omit for the model's default). The response surfaces the trace as `message.reasoning` + `message.reasoning_details` (NOT `reasoning_content`). Low `max_tokens` can yield empty `content` + `finish_reason: length` (normal 200).
* Use "Deepshi API" for the product; "deepshi.ai" for the site/dashboard.

## Facts to keep accurate

* Base URL documented as `https://api.deepshi.ai/v1` (branded placeholder; the live gateway is on Modal).
* Auth header: `Authorization: Bearer sk-bf-...`.
* Status codes: `200` ok, `400` `model_not_found`/`invalid_request_error`, `401` `invalid_api_key`, `402` `insufficient_quota` (out of credits), `403` revoked/not permitted, `429` rate-limited.
* The API is OpenAI-compatible; the OpenAI SDKs work by changing base URL + key.
* Model catalogue (ids, context, pricing, capabilities) comes from `models.md`. Keep `models/text-models.mdx` in sync with it.

## Style preferences

* Use active voice and second person ("you").
* Keep sentences concise — one idea per sentence.
* Use sentence case for headings.
* Bold for UI elements: Click **Create key**.
* Code formatting for file names, commands, paths, model ids, and code references.
* Code examples: prefer a `<CodeGroup>` with curl / Python / JavaScript tabs. Python and JS use the OpenAI SDK pointed at the Deepshi base URL.

## Content boundaries

* Never include real secrets, admin credentials, internal hostnames (e.g. `*.modal.run`), or database details.
* Mark anything unverified with a `{/* TBD: ... */}` MDX comment rather than guessing as fact.