文档 / 开始使用
文档 / 开始使用
完成 API Key、文本同步调用、图像异步任务和统一任务查询的第一次 APIMAX 接入。
本指南帮助你完成 APIMAX 的第一次 API 调用。文本模型使用同步接口，图像、视频、音乐等生成任务通常采用异步模式：先提交任务，再通过统一任务接口查询状态和结果。
登录 APIMAX 后进入用户控制台。调用 API 前请确认账户状态正常，并根据需要在 钱包充值 页面补充余额。
进入 API Keys 页面创建 Key。Key 通常以 sk- 开头，创建后应立即保存在安全位置。
API Key 代表你的调用身份和计费权限。不要把它写入浏览器前端代码、公开仓库、聊天记录或客户端安装包。
本文所有示例使用主入口：
https://api.apimax.ai除客户端明确要求外，不要在 Base URL 后手工拼接具体接口路径。主入口发生网络故障时，可临时使用控制台公布的备用入口排查。
| 类型 | 提交方式 | 获取结果 |
|---|---|---|
| 文本对话 | 同步 HTTP 请求 | 响应中直接返回文本 |
| 图像生成 | 异步任务 | GET /v1/tasks/{id} |
| 视频生成 | 异步任务 | GET /v1/tasks/{id} |
| 音乐生成 | 异步任务 | GET /v1/tasks/{id} |
异步接口提交成功只表示任务已接收，不代表生成已经完成。客户端必须处理 pending、processing、completed 和 failed。
APIMAX 兼容 OpenAI Chat Completions。将模型名替换为控制台模型列表中账号可用的模型 ID：
curl --request POST \
--url https://api.apimax.ai/v1/chat/completions \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "YOUR_TEXT_MODEL",
"messages": [
{"role": "user", "content": "只回复：连接成功"}
]
}'成功时响应中的 choices[0].message.content 是模型回复。部分模型默认流式输出；如果当前客户端不方便处理 SSE，可以在请求中显式设置 stream=false。
Claude 模型也可以使用原生 Messages API：
curl --request POST \
--url https://api.apimax.ai/v1/messages \
--header "x-api-key: YOUR_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "Content-Type: application/json" \
--data '{
"model": "YOUR_CLAUDE_MODEL",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "只回复：连接成功"}
]
}'图像异步接口为 POST /v1/images/async-generations：
curl --request POST \
--url https://api.apimax.ai/v1/images/async-generations \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "gpt-image-2",
"prompt": "白色背景上的极简未来感产品海报，柔和棚拍光线",
"size": "1:1",
"quality": "high",
"n": 1
}'成功后会立即返回任务对象：
{
"id": "task_xxxxxxxxxxxxxxxxx",
"object": "image.generation.task",
"status": "pending",
"progress": 0,
"model": "gpt-image-2"
}模型支持的 size、quality、参考图等参数以对应模型文档为准。不要把其他模型的参数直接复制过来。
图像、视频和音乐任务统一通过以下接口查询：
curl https://api.apimax.ai/v1/tasks/YOUR_TASK_ID \
--header "Authorization: Bearer YOUR_API_KEY"任务完成时，图像任务会在 data 数组返回结果 URL：
{
"id": "task_xxxxxxxxxxxxxxxxx",
"status": "completed",
"progress": 100,
"data": [
{
"url": "https://example.com/result.png",
"url_expires_at": 1780000000
}
]
}不同任务类型的 data 结构不同，应根据所调用接口的文档解析。结果 URL 可能有有效期，生产环境应在任务完成后及时下载并转存。
下面示例提交图像任务并轮询到终态：
import os
import time
import requests
API_KEY = os.environ["APIMAX_API_KEY"]
BASE_URL = "https://api.apimax.ai"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
response = requests.post(
f"{BASE_URL}/v1/images/async-generations",
headers=HEADERS,
json={
"model": "gpt-image-2",
"prompt": "蓝色玻璃材质的极简产品海报",
"size": "1:1",
"quality": "high",
"n": 1,
},
timeout=30,
)
response.raise_for_status()
task_id = response.json()["id"]
deadline = time.time() + 300
while time.time() < deadline:
result = requests.get(
f"{BASE_URL}/v1/tasks/{task_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
result.raise_for_status()
task = result.json()
if task["status"] == "completed":
print(task["data"][0]["url"])
break
if task["status"] == "failed":
raise RuntimeError(task.get("error", "任务失败"))
time.sleep(3)
else:
raise TimeoutError("任务查询超时")failed 状态分别处理。