API 文档
最近更新:2026 年 11 月
从第一个请求开始,逐步查看接口示例与排错说明。
本页目录
- 注册并验证邮箱,或使用 Google 登录。无需绑卡或充值。
- 创建允许 Auto 的密钥,并保存仅显示一次的密钥。打开 API Keys
- 选择 Bash(需 cURL 和 Python 3)、Python 3 或 JavaScript(Node.js 18+)。用自己的密钥替换 your-api-key。Bash 会在本机保存 response.json。
export ITERACOMPUTE_API_KEY="your-api-key"
curl --fail-with-body --max-time 180 https://api.iteracompute.com/v1/chat/completions \
-H "Authorization: Bearer $ITERACOMPUTE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"Auto","messages":[{"role":"user","content":"Reply with exactly: Hello!"}],"max_tokens":512,"reasoning":false}' \
-o response.json && python3 -c 'import json; r=json.load(open("response.json")); text=r["choices"][0]["message"]["content"]; assert text and text.strip(), "Empty model reply: activation is incomplete"; print(text)'import json
from urllib.request import Request, urlopen
api_key = "your-api-key"
payload = {
"model": "Auto",
"messages": [{"role": "user", "content": "Reply with exactly: Hello!"}],
"max_tokens": 512,
"reasoning": False,
}
request = Request(
"https://api.iteracompute.com/v1/chat/completions",
data=json.dumps(payload).encode(),
headers={"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"},
method="POST",
)
with urlopen(request, timeout=180) as response:
result = json.load(response)
text = result["choices"][0]["message"]["content"]
if not text or not text.strip():
raise RuntimeError("Empty model reply: activation is incomplete")
print(text)const apiKey = "your-api-key";
const response = await fetch(
"https://api.iteracompute.com/v1/chat/completions",
{
method: "POST",
headers: {
"Authorization": `Bearer ${apiKey}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"model": "Auto",
"messages": [{"role": "user", "content": "Reply with exactly: Hello!"}],
"max_tokens": 512,
"reasoning": false,
}),
signal: AbortSignal.timeout(180000),
},
);
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
const text = result.choices[0].message.content;
if (!text?.trim()) throw new Error("Empty model reply: activation is incomplete");
console.log(text);成功标准是 choices[0].message.content 非空。每种示例都会打印回复,空回复则报错。预期输出:Hello!(措辞可能不同)。
三种示例均使用免费 Auto 并关闭思考。401/403:检查密钥和模型权限。429:按下方恢复说明处理。
IteraCompute API 兼容 OpenAI 协议:如果你的应用已接入 OpenAI API,迁移只需修改 base_url 与 API Key。Chat Completions、Responses、流式输出与工具调用采用兼容格式,但所选模型须支持相应能力。
API 请求发送至 https://api.iteracompute.com/v1。Chat Completions 与 Responses 请求使用你的 API Key 通过 Authorization 请求头鉴权。
export ITERACOMPUTE_API_KEY="your-api-key"
curl --fail-with-body --max-time 180 https://api.iteracompute.com/v1/chat/completions \
-H "Authorization: Bearer $ITERACOMPUTE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"deepseek/deepseek-v4.1-flash-1017","messages":[{"role":"user","content":"Reply with exactly: Hello!"}],"temperature":0,"max_tokens":128}'请直接使用 Models 接口返回的 provider/model ID,不要添加 iteracompute/ 前缀。可随时查询网关当前发布的模型列表:
curl --fail-with-body https://api.iteracompute.com/v1/modelsModels 接口公开返回网关当前的模型目录。请原样使用其中的 id 值;模型的商业访问权限仍由你的 API Key 与合作协议控制。
模型支持与费用
Chat Completions、Responses、流式和工具调用示例使用付费 DeepSeek V4.1 Flash 1017,按用量扣减 API 余额。请在模型页面核对当前输入、缓存输入和输出价格。免费 Qwen3.8-27B 支持 Chat Completions、流式输出和工具调用,本指南未验证其 Responses API 支持。模型 ID 和推理参数不能随意互换;修改示例前请确认所选模型支持相应端点与参数。
三种语言标签调用的是同一个 HTTP 接口。运行示例前,请在环境变量中设置 ITERACOMPUTE_API_KEY。JavaScript 示例使用 Node.js 18+。
这些示例禁用自动重试。遇到 429 时请查看错误体和 Retry-After;月额度用尽时停止重试。超时、断连或 5xx 后,请保存请求 ID,并在确认处理结果后再决定是否发送新的计费请求。
所有已发布的对话模型均支持 OpenAI Chat Completions 和 Anthropic Messages。Responses 支持范围与模型能力以各模型注明的限制为准。
4. Chat Completions
POST /v1/chat/completions 遵循 OpenAI 的请求与响应格式:
POSThttps://api.iteracompute.com/v1/chat/completions
curl --fail-with-body --max-time 180 https://api.iteracompute.com/v1/chat/completions \
-H "Authorization: Bearer $ITERACOMPUTE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"deepseek/deepseek-v4.1-flash-1017","messages":[{"role":"user","content":"Reply with exactly: Hello!"}],"temperature":0,"max_tokens":128}'# Install once: python -m pip install openai
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.iteracompute.com/v1",
api_key=os.environ["ITERACOMPUTE_API_KEY"],
max_retries=0,
timeout=180.0,
)
resp = client.chat.completions.create(
model="deepseek/deepseek-v4.1-flash-1017",
messages=[{"role": "user", "content": "Reply with exactly: Hello!"}],
temperature=0,
max_tokens=128,
)
print(resp.choices[0].message.content)
print(resp.usage) # prompt_tokens / completion_tokens / total_tokensconst response = await fetch("https://api.iteracompute.com/v1/chat/completions", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.ITERACOMPUTE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "deepseek/deepseek-v4.1-flash-1017",
messages: [{role: "user", content: "Reply with exactly: Hello!"}],
temperature: 0,
max_tokens: 128,
}),
signal: AbortSignal.timeout(180000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result.choices[0].message.content);Anthropic Messages
此示例使用 DeepSeek V4.1 Flash 1017,也可选择密钥有权调用的任何已发布对话模型。Python 示例仅使用标准库。Messages 保留 Anthropic 原生响应和错误格式,流以 message_stop 结束,而不是 [DONE]。
POSThttps://api.iteracompute.com/v1/messages
curl --fail-with-body --max-time 180 https://api.iteracompute.com/v1/messages \
-H "x-api-key: $ITERACOMPUTE_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d @- <<JSON
{
"model": "deepseek/deepseek-v4.1-flash-1017",
"max_tokens": 128,
"messages": [{"role": "user", "content": "Hello!"}]
}
JSONimport json
import os
from urllib.request import Request, urlopen
request = Request(
"https://api.iteracompute.com/v1/messages",
data=json.dumps({
"model": "deepseek/deepseek-v4.1-flash-1017",
"max_tokens": 128,
"messages": [{"role": "user", "content": "Hello!"}],
}).encode(),
headers={
"x-api-key": os.environ["ITERACOMPUTE_API_KEY"],
"anthropic-version": "2023-06-01",
"Content-Type": "application/json",
},
method="POST",
)
with urlopen(request, timeout=180) as response:
result = json.load(response)
print("".join(block["text"] for block in result["content"] if block["type"] == "text"))const response = await fetch("https://api.iteracompute.com/v1/messages", {
method: "POST",
headers: {
"x-api-key": process.env.ITERACOMPUTE_API_KEY,
"anthropic-version": "2023-06-01",
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "deepseek/deepseek-v4.1-flash-1017",
max_tokens: 128,
messages: [{role: "user", content: "Hello!"}],
}),
signal: AbortSignal.timeout(180000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result.content.filter(block => block.type === "text").map(block => block.text).join(""));5. Responses API
POST /v1/responses 支持 Codex 等客户端使用的 OpenAI Responses API:
POSThttps://api.iteracompute.com/v1/responses
curl --fail-with-body --max-time 180 https://api.iteracompute.com/v1/responses \
-H "Authorization: Bearer $ITERACOMPUTE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"deepseek/deepseek-v4.1-flash-1017","input":"Reply with exactly: Hello!","max_output_tokens":128}'# Install once: python -m pip install openai
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.iteracompute.com/v1",
api_key=os.environ["ITERACOMPUTE_API_KEY"],
max_retries=0,
timeout=180.0,
)
response = client.responses.create(
model="deepseek/deepseek-v4.1-flash-1017",
input="Reply with exactly: Hello!",
max_output_tokens=128,
)
print(response.output_text)const response = await fetch("https://api.iteracompute.com/v1/responses", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.ITERACOMPUTE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "deepseek/deepseek-v4.1-flash-1017",
input: "Reply with exactly: Hello!",
max_output_tokens: 128,
}),
signal: AbortSignal.timeout(180000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result.output.filter(item => item.type === "message").flatMap(item => item.content || [])
.filter(block => block.type === "output_text").map(block => block.text).join(""));使用已上架的图片模型和有权限的 API Key 调用图片接口。调用前请在模型目录确认当前可用状态。
生成请求包含模型 ID、提示词或原生 contents,请只使用所选模型支持的字段。通过 API Key 鉴权,并将返回的 base64 图片解码保存到本机。
POSThttps://api.iteracompute.com/v1/images/generations
编辑时需要准备参考图,例如 reference.png。图片和提示词均计入输入用量,可将编辑结果解码保存为 edited.png。
请按模型声明的编辑格式接入:通过 /v1/images/edits 上传 multipart 文件,或通过 /v1/images/generations 传入 base64 inlineData 参考图。文件 MIME 须与实际内容一致。
响应包含 data[].b64_json、mime_type 和以 USD 计价的 usage.cost。示例会解码图片,不将 base64 当作 URL。费用按当前模型价格及实际文本、图片、思考 Token 用量计算。
- 图片调用不使用免费对话额度。每张图片独立准入和计费,费用向上取整到美元微元;当前价格请查看模型目录。
- 建议从 n=1 开始,每次可请求 1–4 张。参考图支持 PNG、JPEG、WebP,最多四张,含 mask 的解码总量上限为 8 MiB;完整请求上限为 12 MiB。
- 尺寸、质量和流式支持取决于所选模型。图片 SSE 事件与对话流不同,请按模型声明处理;普通非流式响应可直接解码保存。
价格预估不会生成图片。reservation_cost_micros 表示保守余额预留,不是输出硬上限或最终费用;maximum_cost_micros 使用请求输出上限计算。具体字段取决于模型,最终均按实际用量结算。
POSThttps://api.iteracompute.com/v1/images/price-estimate
HTTP 207 时请逐项检查结果并保存已完成图片,前面的图片可能已计费。HTTP 422 即使未交付完整图片,也可能包含应计费用量。缺失用量或超时不代表免费;请保存请求 ID,确认结果后再决定是否发起新的付费请求。
6. 流式输出(SSE)
设置 "stream": true 即可接收 Server-Sent Events。内容块按生成进度实时下发;token 用量包含在最后一个携带 usage 的内容块中,位于结束标记 [DONE] 之前。请将一次流式请求视为一个整体:已有 token 输出后,请求不会被透明重试。
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.iteracompute.com/v1",
api_key=os.environ["ITERACOMPUTE_API_KEY"],
max_retries=0,
timeout=180.0,
)
stream = client.chat.completions.create(
model="deepseek/deepseek-v4.1-flash-1017",
messages=[{"role": "user", "content": "Reply with exactly: Hello!"}],
stream=True,
stream_options={"include_usage": True},
temperature=0,
max_tokens=128,
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")
if chunk.usage: # final chunk: token usage
print("\n", chunk.usage)7. 工具调用
工具结果通过新请求回传,同样受密钥速率和并发限制。遇到 429 时请查看 Retry-After 并停止本次尝试,不要并发发送副本。
通过 tools 参数声明工具,格式遵循 OpenAI function calling。模型决定调用工具时,响应中会包含 tool_calls;将工具执行结果以 "tool" 角色回传即可继续对话。
import json
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.iteracompute.com/v1",
api_key=os.environ["ITERACOMPUTE_API_KEY"],
max_retries=0,
timeout=180.0,
)
messages = [{"role": "user", "content": "What is the weather in Singapore?"}]
tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get current weather for a city",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
},
}]
resp = client.chat.completions.create(
model="deepseek/deepseek-v4.1-flash-1017",
messages=messages,
tools=tools,
tool_choice={"type": "function", "function": {"name": "get_weather"}},
max_tokens=512,
)
assistant_message = resp.choices[0].message
messages.append(assistant_message)
for call in assistant_message.tool_calls or []:
arguments = json.loads(call.function.arguments)
result = {"city": arguments["city"], "temperature_c": 29}
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(result),
})
final = client.chat.completions.create(
model="deepseek/deepseek-v4.1-flash-1017",
messages=messages,
tools=tools,
max_tokens=512,
)
print(final.choices[0].message.content)8. 错误码
Chat Completions 和 Responses 的错误采用 OpenAI 错误格式,响应体为 {"error": {"message", "type", "code"}}:
| 状态码 | 含义 |
|---|---|
| 400 | 请求无效 - JSON 格式错误或缺少必填参数 |
| 401 | 鉴权失败 - API Key 缺失或无效 |
| 403 | 该 Key 无权访问此模型或执行此操作。若使用受限 Key,请在控制台将新 Model ID 加入该 Key 的允许模型列表,保存后重试。 |
| 404 | 模型或接口不存在 |
| 429 | 速率或容量限制:查看 error.code,并按下方说明恢复 |
| 500 | 内部错误 - 保存请求 ID,确认处理结果后再决定是否重试 |
| 503 | 模型暂不可用 - 请退避重试 |
Auto 的免费权益由账户内所有 API Key 共享。Free / Starter / Pro 每个 UTC 自然月提供 30M / 100M / 300M tokens,上下文为 128K / 128K / 256K。三档均为每账号 1 个排队或生成中的请求,不设 TPM 或每日 Token 上限。累计已完成净充值 $10 或 $50 可解锁 Starter 或 Pro,并享有共享容量的排队优先级。请求可能排队或变慢,不保证速度与延迟。购买的 Auto 套餐额度遵循各自合同限制。其他模型保留 API Key 限制,包括已配置的 RPM 或 TPM 上限。
按原因处理 429
重试前先看 error.code。月额度拒绝返回 free_model_monthly_limit。已有免费请求尚未结束、队列满、排队超时和其他容量拒绝统一返回 provider_rate_limit,公开响应无法区分这些原因。请在控制台 → Free 查看账户限制,并确认前一个请求是否仍在进行。
- 月额度已用完或被预留
free_model_monthly_limit 停止自动重试。在控制台 → Free 查看已用、预留 tokens 和重置时间。等下一个 UTC 自然月重置、升级后新增额度足够,或已有预留释放后再尝试。反复重试不会增加额度;升级保留本月用量,超额不会自动转为付费。
- 已有免费请求正在排队或生成
provider_rate_limit 等待正在排队或生成的请求结束后再试,并遵循 Retry-After。Free、Starter、Pro 三档在账户内所有 Key 和免费路由之间均共用 1 个未完成的免费请求名额;切换 Key 或 Model ID 不会增加名额。不要并发重复发送。在控制台 → Free 查看用量和预留。公开错误码 provider_rate_limit 也可能表示其他容量限制。
- 容量:队列已满
provider_rate_limit 等待队列无法再接收新请求。至少等 Retry-After 后才重试,并使用指数退避和随机抖动、减少并发。达到重试次数上限或应用截止时间即停止。同一错误码也可能代表其他容量限制,不能据此推断队列位置。在控制台 → Free 查看账户限制;持续失败时携请求 ID 联系支持。
- 容量:排队等待超时
provider_rate_limit 请求排队 120 秒仍未获得容量。再次尝试会重新排队;只有剩余截止时间允许时,才在 Retry-After 和退避后重试。达到截止时间或重试上限即停止,不要并发重复发送。公开错误码与队列满相同。反复失败时,携请求 ID 和发生时间联系支持。
充值前的免费模型 FAQ
本次免费活动于 2026 年 11 月 24 日 00:00(美国太平洋时间)结束。截止前已完成充值且净充值大于 0 的用户继续保留原有免费档位。此后,共享免费 Auto 仅向这些老充值用户和当前有效套餐用户开放;新充值不再获得或升级免费权益。套餐内 Auto 额度与每月共享免费权益独立计算。
新账户如何开始免费调用?
活动结束前,邮箱验证后即可使用完整的每月 30M 免费额度。截止后,免费 Auto 仅向符合条件的老充值用户和套餐用户开放。Free、Starter、Pro 三档均为每账号 1 个排队或生成中的请求,共享容量速度较慢,所有 Key 与 Auto 共用。不设每日 Token 上限,也无需累计调用次数或跨 UTC 日期升级。月用量包含输入和输出;上下文上限、共享容量队列和风控复核仍然适用。
疑似关联账户会如何处理?
我们结合设备关联、注册密度、调用节奏和验证结果决定是否要求追加验证。同 IP 不会单独确认账户关联,公司、校园和家庭可以共用网络。通过人机验证本身不能证明账户属于不同主体。只有经复核确认同一主体批量领取试用后,相关账户才共用一份免费月额度和 1 个排队或生成中的请求名额,并共享速度可能较慢的容量,所有 Key 与 Auto 一并计算。如需复核或申诉,请联系支持。
套餐 Auto 与共享免费权益是同一份额度吗?
不是。套餐内 Auto 额度与每月共享免费权益有各自独立的额度和用量账本。套餐 Auto 按购买周期及合同限制执行,并享有优先调度。请求先使用套餐 Auto;未被套餐覆盖的请求仅在账户仍符合免费资格时使用共享免费权益,可能排队或响应较慢。购买或续费套餐不会重置共享免费用量。套餐到期后,只有符合截止前充值条件的用户继续保留共享免费资格。
为什么免费请求会排队或变慢?
免费 Auto 使用共享的闲置 GPU 资源。目前访问量已超过可用闲置资源,可能出现排队、响应变慢或暂时不可用。充值档享有排队优先级,但不代表预留 GPU,也不保证吞吐、延迟或 SLA。感谢大家理解。
免费模型的部署精度会一直相同吗?
模型精度和量化方式以实际部署为准,后续可能变化。模型名称不代表全精度,也不保证不同部署的结果完全一致。充值前请先用自己的典型任务验证正确性、工具调用和响应时间,确认是否符合需求。
充值更多会增加免费模型权益吗?
对于截止前已充值的用户,累计净充值满 $10 对应 Starter:每月 100M tokens、128K 上下文;满 $50 解锁 Pro:每月 300M tokens、256K 上下文。两档均享有排队优先级。超过 $50 的充值不会自动增加免费模型权益。充值保留为可消费 API 余额,这些门槛不是月费。 仅统计截止前已完成到账的充值本金;此后充值不能提高这些档位,退款仍会减少符合条件的净充值本金。
“终身权益”具体包括什么?
对符合截止前充值条件的用户,“终身权益”指持续保留所达 Starter 或 Pro 档的月 token 额度、上下文上限和排队优先级,免费模型升级或更换后仍享有同等档位参数的权益。消费余额不降档;退款可能调整档位,违规仍按现有规则处理。这不代表固定模型名称、权重或精度,也不承诺无限用量、专属算力或服务永久可用。
免费模型会变吗?Qwen4-27B 何时上线?
免费模型后续可能升级、更换或调整。我们正在计划上线 Qwen4-27B,仍在等待官方模型开源,目前没有确定的上线时间或已公布规格。已充值用户继续保留上述同等档位权益;未充值用户未来的模型访问、额度和限制无法保证。
接入问题请联系:support@iteracompute.com