HTTP REST

Tapapi 的主线接口可以直接用 HTTP 调用。只要你的语言能发 HTTPS 请求，就可以接入文本和图片能力；视频 API 当前按受控开放处理，生产调用前需要先确认模型、价格和账号权限。

基础信息

项目	值
Base URL	`https://tapapi.ai/v1`
鉴权	`Authorization: Bearer sk-xxx`
文本接口	`POST /v1/chat/completions`
Responses 接口	`POST /v1/responses`，按模型详情确认
图片接口	`POST /v1/images/generations`
视频接口	`/v1/videos` 系列，受控开放
模型列表	`GET /v1/models`

本地服务也兼容部分上游风格的 Key 传法，但公开文档统一主推 Bearer Token，便于排障和迁移。

文本请求

curl https://tapapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {"role": "user", "content": "用一句话解释 Tapapi 是什么"}
    ]
  }'

成功后读取：

choices[0].message.content

流式文本

curl -N https://tapapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "stream": true,
    "stream_options": {"include_usage": true},
    "messages": [
      {"role": "user", "content": "写一段 100 字的产品介绍"}
    ]
  }'

底层响应是 SSE：

data: {...}
data: {...}
data: [DONE]

业务代码通常读取每个 chunk 的 choices[0].delta.content。生产解析时要跳过空内容、ping/keep-alive 和无内容的 delta，收到 data: [DONE] 后结束。

Responses 请求

/v1/chat/completions 是文本 HTTP 接入的默认主线。/v1/responses 是可选文本协议，适合已经确认模型和字段支持的场景：

curl https://tapapi.ai/v1/responses \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "input": "用一句话解释 Tapapi 是什么"
  }'

Responses 的返回结构和 Chat Completions 不完全一样。接入前先用真实模型测试字段，再写入生产解析逻辑。

图片生成

curl https://tapapi.ai/v1/images/generations \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "prompt": "a clean product photo of a white ceramic mug",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

成功后读取：

data[0].url

或者：

data[0].b64_json

生产代码需要同时兼容 url 和 b64_json。size 必须使用英文字母 x，例如 1024x1024，不要写成 1024×1024。生产解析建议：

项	建议
`data=[]`	当作无有效结果处理，记录 `request_id` 和请求摘要
返回数量	记录请求 `n`、实际 `data.length` 和成功转存数量
`url`	后端下载后转存到自有 COS、S3、R2 或 OSS
`b64_json`	解码后写入文件或上传对象存储
部分成功	如果响应包含 `metadata.tapapi_partial`，按实际返回张数处理

视频 HTTP 入口

视频 API 当前不是默认全量开放能力。只有控制台可见模型、价格已确认、账号有权限时，才适合生产调用。推荐流程：

POST /v1/videos
  -> GET /v1/videos/{task_id}
  -> completed 后 GET /v1/videos/{task_id}/content

视频请求字段会随模型变化，不要把某个模型的 seconds、size、aspect_ratio、参考图字段直接复用到所有视频模型。更多见视频 API 和任务与输出。

模型列表

curl https://tapapi.ai/v1/models \
  -H "Authorization: Bearer sk-xxx"

模型是否可用、价格和权限以控制台为准。文档示例里的模型名只用于说明调用结构。

错误响应

OpenAI-compatible 接口的错误通常是：

{
  "error": {
    "message": "...",
    "type": "new_api_error",
    "param": "",
    "code": "invalid_request"
  }
}

响应头会返回请求标识，排障时优先保存：

X-Oneapi-Request-Id: 20260609...

任务/视频类接口的错误可能不是标准 { "error": ... }，也可能返回顶层 code、message、data。生产日志不要只保存一段错误文本，至少记录 HTTP 状态码、error.type、error.code、error.message、request_id 和业务 task_id。处理建议：

HTTP	是否重试	建议
400	否	修正请求字段
401 / 403	否	检查 API Key、账户状态和权限
429	是	指数退避，限制最大次数
临时 5xx	是	重试 1-2 次，仍失败则记录并告警
504 / 524	先排查	查业务状态和账单，再决定是否补跑

更多见错误码与重试。

生产 HTTP 建议

项	建议
API Key	只放服务端环境变量，不放 URL query、前端代码或公开配置
timeout	文本和图片按业务设置等待时间；长任务进入队列或轮询
重试	只对 429、临时 5xx、网络中断做有限重试
幂等	保存业务 `task_id`，避免刷新、重复点击、worker 重启造成重复请求
日志	保存模型、接口、请求摘要、HTTP 状态码、`request_id` 和最终用量
输出	图片和视频结果尽快转存，不长期依赖临时 URL

不建议当前使用

路径	原因
`/v1/images/variations`	当前返回 not implemented
`/v1/files`	当前返回 not implemented
`/v1/fine-tunes`	当前返回 not implemented
`/v1/tapapi/images/advanced` 的 `image_urls` / `webhook`	代码会在计费前拦截，暂不开放
`/v1/videos`	受控开放，未确认模型、价格和权限前不要生产依赖

下一步

场景	文档
已有 OpenAI SDK	OpenAI SDK 迁移
Python 完整示例	Python
Node.js / TypeScript	Node.js / TypeScript
PHP / Laravel	PHP / Laravel
错误与重试	错误码与重试
生产上线检查	上线 Checklist

SDK 与语言

常用工具

基础信息

文本请求

流式文本

Responses 请求

图片生成

视频 HTTP 入口

模型列表

错误响应

生产 HTTP 建议

不建议当前使用

下一步

​基础信息

​文本请求

​流式文本

​Responses 请求

​图片生成

​视频 HTTP 入口

​模型列表

​错误响应

​生产 HTTP 建议

​不建议当前使用

​下一步

基础信息

文本请求

流式文本

Responses 请求

图片生成

视频 HTTP 入口

模型列表

错误响应

生产 HTTP 建议

不建议当前使用

下一步