API 接入文档

三步完成首次调用

1. 注册并充值

   完成邮箱验证，按需要充值余额、订阅套餐或兑换额度卡密。

2. 创建 API 密钥

   进入用户控制台的“API 密钥”，创建并妥善保存以 sk- 开头的密钥。

3. 查询模型再调用

   先请求 /v1/models 获取真实模型 ID，避免使用未配置的模型名称。

curl https://api.dhhapi.com/v1/models \
  -H "Authorization: Bearer sk-your-api-key"

Base URL 与请求头

推荐使用 Bearer Token。Claude 客户端可使用 x-api-key，Gemini 客户端也支持 x-goog-api-key。请勿把密钥放进 URL、浏览器前端代码或公开仓库。

Authorization: Bearer sk-your-api-key
Content-Type: application/json

模型名称以实时列表为准

不同 API 密钥可能绑定不同分组，因此可用模型、倍率和能力并不一定相同。不要仅凭第三方教程猜测模型名，也不要把网页显示名称当作模型 ID。

文本模型不一定支持生图，生图模型也不一定支持图片编辑。接口返回“model not found”或“not supported”时，应先确认密钥分组和模型能力。

当前网关端点

三种常用协议

OpenAI Chat Completions

curl https://api.dhhapi.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 获取的模型 ID",
    "messages": [
      {"role": "system", "content": "你是一个简洁的中文助手。"},
      {"role": "user", "content": "用三句话介绍大航海时代。"}
    ],
    "stream": false
  }'

非流式响应的主要文本通常位于 choices[0].message.content。

OpenAI Responses

curl https://api.dhhapi.com/v1/responses \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 获取的模型 ID",
    "input": "请列出三个跨境电商选品原则",
    "stream": false
  }'

Claude Messages

curl https://api.dhhapi.com/v1/messages \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 获取的 Claude 模型 ID",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "你好，请介绍一下自己"}
    ]
  }'

使用 SSE 持续接收内容

在 Chat Completions、Responses 或 Messages 请求中设置 "stream": true。客户端应逐行读取 data: 事件，不要等待整个响应结束。

curl -N https://api.dhhapi.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 获取的模型 ID",
    "messages": [{"role": "user", "content": "写一段产品介绍"}],
    "stream": true
  }'

把文字和图片放在同一条消息中

图片理解使用支持视觉能力的对话模型，而不是 /v1/images/* 生图接口。图片可以是公网 HTTPS URL，也可以是完整的 Data URL。

使用公网图片 URL

curl https://api.dhhapi.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "支持视觉的模型 ID",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "请识别图片中的商品，并输出中文卖点。"},
        {
          "type": "image_url",
          "image_url": {"url": "https://example.com/product.jpg"}
        }
      ]
    }]
  }'

使用本地图片转 Base64

# PowerShell：先生成完整 Data URL
$base64 = [Convert]::ToBase64String(
  [IO.File]::ReadAllBytes("C:\images\product.jpg")
)
$imageUrl = "data:image/jpeg;base64,$base64"

# 将 $imageUrl 填入上方 image_url.url 字段

生成新图、参考图和本地图片编辑

生图能力只对 OpenAI 或 Grok 类型的分组开放。模型名称、尺寸和并发能力以 /v1/models 与后台渠道配置为准。

文字生成图片

curl https://api.dhhapi.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "电商主图：白色背景上的蓝色旅行箱，棚拍光线",
    "size": "1024x1024",
    "n": 1,
    "response_format": "b64_json"
  }'

上传本地图片进行编辑

curl https://api.dhhapi.com/v1/images/edits \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "prompt=保留主体，把背景改成海边日落" \
  -F "image=@C:\images\product.png" \
  -F "size=1024x1024" \
  -F "n=1"

使用图片 URL 编辑

curl https://api.dhhapi.com/v1/images/edits \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "把背景改成干净的摄影棚，并保留产品文字",
    "images": [
      {"image_url": "https://example.com/input.png"}
    ],
    "size": "1024x1024"
  }'

本地上传采用 multipart/form-data，单个上传部分最大 20 MB。不要手工设置 multipart 的 boundary，让 curl 或 SDK 自动生成。

避免长任务被代理超时中断

异步端点适合耗时较长的生图和图片编辑。该功能只有在管理员已开启并配置对象存储时可用，否则会返回 404。

提交任务

curl -i https://api.dhhapi.com/v1/images/generations/async \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一座暴风雪中的灯塔",
    "size": "1536x1024"
  }'

成功提交返回 202 Accepted、task_id、poll_url 和建议轮询间隔。

查询任务

curl https://api.dhhapi.com/v1/images/tasks/imgtask_xxx \
  -H "Authorization: Bearer sk-your-api-key"

必须使用提交任务时的同一把 API 密钥轮询。建议每 3 秒查询一次；任务及结果默认保留 24 小时，单个任务最长执行 30 分钟。

只需要替换 Base URL 和 API Key

Python · OpenAI SDK

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.dhhapi.com/v1",
    timeout=300.0,
)

response = client.chat.completions.create(
    model="从 /v1/models 获取的模型 ID",
    messages=[{"role": "user", "content": "你好"}],
)
print(response.choices[0].message.content)

Node.js · OpenAI SDK

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DHH_API_KEY,
  baseURL: "https://api.dhhapi.com/v1",
  timeout: 300_000,
});

const response = await client.chat.completions.create({
  model: "从 /v1/models 获取的模型 ID",
  messages: [{ role: "user", content: "你好" }],
});

console.log(response.choices[0].message.content);

Python · Anthropic SDK

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-api-key",
    base_url="https://api.dhhapi.com",
    timeout=300.0,
)

message = client.messages.create(
    model="从 /v1/models 获取的 Claude 模型 ID",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}],
)
print(message.content[0].text)

先看 HTTP 状态，再看错误对象

错误响应通常包含 error.type、error.code 和 error.message。不要只判断文字内容，也不要把上游错误统一当成“密钥失效”。

稳定接入建议

推荐退避：1s → 2s → 4s → 8s（每次增加 0–500ms 随机抖动）
建议最大重试：3–5 次
生产环境请记录：HTTP 状态、error.code、error.message、request_id、model

需要协助时，请提供请求时间、接口路径、模型 ID、HTTP 状态和脱敏后的错误响应。请勿发送完整 API Key。