Skip to main content

​
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. 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.
  • 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.