# API 概览 (https://hypit.ai/zh/api-reference/)

> 一套 OpenAI 形状的 API，扇出到二十多家生成式媒体厂商，按额度计费。

hypit.ai 对外只有一套 HTTP API，背后扇出到二十多家上游的图片、视频、音频与对话厂商。你只持有一把
Key、一份余额、一种协议格式；路由、故障转移和计量都在我们这一侧完成。

这套接口是**按 OpenAI 的形状设计**的。`/v1/chat/completions` 和 `/v1/models` 与官方 OpenAI SDK
完全兼容，把 base URL 指过来，现有代码不用改。生成式媒体端点沿用同样的约定（snake\_case 字段、
`{"error": {...}}` 错误信封、Unix 秒时间戳），但返回的是一个 **Job** 而不是成品——因为一段视频不
可能在一次 HTTP 请求里生成完。

## Base URL [#base-url]

```text
https://hypit.ai/v1
```

Google 原生接口在上一层，位于 `https://hypit.ai/v1beta/models/...`，见
[Gemini 原生接口](/zh/api-reference/gemini)。

## 环境变量 [#环境变量]

客户端需要的东西全在这两个变量里：

```bash
export HYPIT_API_KEY="sk-hh-..."
export HYPIT_BASE_URL="https://hypit.ai/v1"
```

这里刻意用 `HYPIT_*` 而不是 `OPENAI_*`：这是我们自己的凭据，而一个已经在调 OpenAI 的项目应该能
把两套配置并存。代价只是构造客户端时多写一行显式参数——其实这样更清楚，因为它把「客户端指向了
哪里」说了出来。

## 配合 OpenAI SDK 使用 [#配合-openai-sdk-使用]

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HYPIT_API_KEY"],
    base_url=os.environ.get("HYPIT_BASE_URL", "https://hypit.ai/v1"),
)

completion = client.chat.completions.create(
    model="gemini-3.1-pro",
    messages=[{"role": "user", "content": "用一句话说明 Hypit 是什么。"}],
)
print(completion.choices[0].message.content)
```

```js
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.HYPIT_API_KEY,
  baseURL: process.env.HYPIT_BASE_URL ?? "https://hypit.ai/v1",
});

const completion = await client.chat.completions.create({
  model: "gemini-3.1-pro",
  messages: [{ role: "user", content: "用一句话说明 Hypit 是什么。" }],
});
console.log(completion.choices[0].message.content);
```

<Callout type="warn" title="SDK 的封装方法只覆盖同步端点">
  `client.chat.completions.*`、`client.models.*`、`client.audio.speech.*` 和
  `client.audio.transcriptions.*` 可以直接用。`client.images.generate()` **不行**：我们的图片、视频和
  音乐端点返回的是 `202 Accepted` 加一个 Job 信封，不是成品的 `data[]` 数组。这几个端点请用普通
  HTTP 调用并轮询，下面每一页都给了完整写法。
</Callout>

## 第一次调用 [#第一次调用]

```bash
curl https://hypit.ai/v1/models \
  -H "Authorization: Bearer $HYPIT_API_KEY"
```

这一条能返回列表，本站其余内容就都能跑通。

## 端点一览 [#端点一览]

| 端点                                | 方法   | 形态                 |
| --------------------------------- | ---- | ------------------ |
| `/v1/models`                      | GET  | 列出这把 Key 能路由到的全部模型 |
| `/v1/models/{model}`              | GET  | 单个模型卡片，含额度费率       |
| `/v1/chat/completions`            | POST | 同步，支持 SSE 流式       |
| `/v1/images/generations`          | POST | 异步——返回 Job         |
| `/v1/images/edits`                | POST | 异步——返回 Job         |
| `/v1/videos`                      | POST | 异步——返回 Job         |
| `/v1/audio/music`                 | POST | 异步——返回 Job         |
| `/v1/audio/speech`                | POST | 同步，返回音频字节          |
| `/v1/audio/transcriptions`        | POST | 同步，返回文本            |
| `/v1/jobs/{job_id}`               | GET  | 任务状态               |
| `/v1/jobs/{job_id}/assets`        | GET  | 带签名的下载链接           |
| `/v1beta/models/{model}:{action}` | POST | Google Gemini 原生透传 |

接下来先读[认证](/zh/api-reference/authentication)；如果你要生成任何画面，紧接着读
[异步任务](/zh/api-reference/jobs)——踩坑基本都在那一页。