AI 运行时

核心 LLM 推理（对话、嵌入、视觉、图像生成、语音 TTS/ASR）与 OpenAI 兼容：用官方 openai SDK 指向 infrai 的 base_url 即可调用。此处列出的是 infrai 原生扩展：批处理、成本/Token 工具、rerank、图像超分、TTS 音色与实时语音会话。

概览

基础路径: https://api.infrai.cc/v1/ai

鉴权头: Authorization: Bearer $INFRAI_API_KEY

bash

# Call any /v1/ai capability over raw HTTP — no SDK to install.
# curl:
curl https://api.infrai.cc/v1/ai/... \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json"

方法

ai.batch.submit

POST /v1/ai/batch/submit

提交一批 AI 请求作为单个异步批处理任务，批量模式按成本原价透传。

参数

名称	类型	必填	说明
`requests`	`BatchRequestItem[]`	必填	批处理请求条目数组，每条含 capability 与 body。
`batch_timeout`	`string`	可选	批处理的最长完成时限（如 24h），超时未完成的条目按失败处理。
`metadata`	`Record<string, unknown>`	可选	附加到批处理任务上的自定义键值元数据。
`idempotency_key`	`string`	可选	可选去重 key；相同重试将返回同一结果。

BatchSubmitResult { batch_id, state, total_count, estimated_eta?, estimated_cost_usd? }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/ai/batch/submit \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requests": []}'

ai.batch.status

GET /v1/ai/batch/status/{id}

查询批处理任务的状态、进度与已完成/失败计数。

参数

名称	类型	必填	说明
`batch_id`	`string`	必填	目标批处理任务的 ID。

BatchStatus { batch_id, state, progress, total_count, completed_count, failed_count, created_at, total_cost_usd? }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/ai/batch/status/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

ai.batch.results

GET /v1/ai/batch/results/{id}

分页拉取批处理任务的逐条结果。

参数

名称	类型	必填	说明
`batch_id`	`string`	必填	目标批处理任务的 ID。
`cursor`	`string`	可选	分页游标：传入上一页返回的 next_cursor 获取下一页。
`limit`	`number`	可选	单页返回条数上限。

BatchResultsPage { items, total_count, next_cursor?, download_url? }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/ai/batch/results/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

ai.batch.list

GET /v1/ai/batch/list

分页列出本账户的全部批处理任务。

参数

名称	类型	必填	说明
`cursor`	`string`	可选	分页游标：传入上一页返回的 next_cursor 获取下一页。
`limit`	`number`	可选	单页返回条数上限。

BatchListResult { batches, total_count, next_cursor? }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/ai/batch/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

ai.batch.cancel

POST /v1/ai/batch/cancel/{id}

取消一个进行中的批处理任务。

参数

名称	类型	必填	说明
`batch_id`	`string`	必填	要取消的批处理任务的 ID。
`idempotency_key`	`string`	可选	可选去重 key；相同重试将返回同一结果。

BatchStatus { batch_id, state, ... }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/ai/batch/cancel/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"batch_id": "..."}'

ai.batch.export

POST /v1/ai/batch/export/{id}

将批处理结果导出为 jsonl 或 csv 文件并返回下载任务。

参数

名称	类型	必填	说明
`batch_id`	`string`	必填	要导出的批处理任务的 ID。
`format`	`"jsonl" \| "csv"`	可选	导出文件格式：jsonl 或 csv。
`conversation_id`	`string`	可选	可选，仅导出指定会话的结果。
`metadata`	`Record<string, unknown>`	可选	附加到导出任务上的自定义键值元数据。
`idempotency_key`	`string`	可选	可选去重 key；相同重试将返回同一结果。

ExportJob { export_id, state, format?, download_url?, expires_at?, created_at }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/ai/batch/export/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

ai.batch.set_retention

POST /v1/ai/batch/set_retention/{id}

设置批处理结果的保留天数，到期自动清除。

参数

名称	类型	必填	说明
`batch_id`	`string`	必填	目标批处理任务的 ID。
`retention_days`	`number`	必填	结果保留天数，到期后自动删除。
`idempotency_key`	`string`	可选	可选去重 key；相同重试将返回同一结果。

BatchStatus { batch_id, state, ... }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/ai/batch/set_retention/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"batch_id": "..."}'

ai.cost.estimate

POST /v1/ai/cost/estimate

在调用前估算一次 AI 请求的 token 数与分项成本。

参数

名称	类型	必填	说明
`messages`	`string \| ChatMessage[]`	必填	用于估算的消息，可为字符串或消息数组。
`model`	`string`	可选	显式模型 id；跳过 task/prefer 路由。
`expected_output_tokens`	`number`	可选	预期的输出 token 数，用于估算输出侧成本。
`cache_strategy`	`"vendor" \| "infrai" \| "none"`	可选	使用哪一层缓存。
`batch_mode`	`boolean`	可选	以批处理任务运行以获得折扣价。
`tools`	`Tool[]`	可选	工具/函数调用定义。

CostEstimate { model, vendor, vendor_region?, prompt_tokens, expected_output_tokens, breakdown }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/ai/cost/estimate \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages": []}'

ai.cost.compare

POST /v1/ai/cost/compare

对同一请求在多个模型上估算并对比成本。

参数

名称	类型	必填	说明
`messages`	`string \| ChatMessage[]`	必填	用于对比估算的消息，可为字符串或消息数组。
`models`	`string[]`	可选	参与成本对比的模型 ID 列表。
`expected_output_tokens`	`number`	可选	预期的输出 token 数，用于估算输出侧成本。
`cache_strategy`	`"vendor" \| "infrai" \| "none"`	可选	使用哪一层缓存。
`batch_mode`	`boolean`	可选	以批处理任务运行以获得折扣价。
`tools`	`Tool[]`	可选	工具/函数调用定义。

{ estimates: CostEstimate[] }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/ai/cost/compare \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages": []}'

ai.tokens.count

POST /v1/ai/tokens/count

统计一组消息在指定模型下的输入 token 数。

参数

名称	类型	必填	说明
`messages`	`string \| ChatMessage[]`	必填	要统计 token 数的消息，可为字符串或消息数组。
`model`	`string`	可选	显式模型 id；跳过 task/prefer 路由。
`tools`	`Tool[]`	可选	工具/函数调用定义。

TokenCountResult { prompt_tokens, model }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/ai/tokens/count \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages": []}'

ai.image.upscale

POST /v1/ai/image/upscale

将图片按 2 倍或 4 倍无损放大。

参数

名称	类型	必填	说明
`image`	`string`	必填	待放大的源图片，URL 或 base64。
`factor`	`2 \| 4`	可选	放大倍数，2 或 4。
`idempotency_key`	`string`	可选	可选去重 key；相同重试将返回同一结果。

ImageUpscaleResult { image, original_size, new_size }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/ai/image/upscale \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image": "..."}'

ai.tts.voices

GET /v1/ai/tts/voices

分页列出文本转语音可用的音色列表。

参数

名称	类型	必填	说明
`cursor`	`string`	可选	分页游标：传入上一页返回的 next_cursor 获取下一页。
`limit`	`number`	可选	单页返回条数上限。

VoiceListResult { voices, total_count, next_cursor? }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/ai/tts/voices \
  -H "Authorization: Bearer $INFRAI_API_KEY"

全部能力

本模块全部已路由能力——完整的对外 REST 契约。上方方法是带讲解的入门示例,此表是完整参考。

能力	端点	说明
`ai.batch.cancel`	`POST /v1/ai/batch/cancel/{id}`	Cancel an in-progress batch job (idempotent).
`ai.batch.export`	`POST /v1/ai/batch/export/{id}`	Export batch results to a JSONL or CSV file and return a download job.
`ai.batch.list`	`GET /v1/ai/batch/list`	List all batch jobs on the account with pagination.
`ai.batch.results`	`GET /v1/ai/batch/results/{id}`	Fetch per-item results of a batch job with pagination.
`ai.batch.set_retention`	`POST /v1/ai/batch/set_retention/{id}`	Set the retention period for batch results, auto-purged on expiry (idempotent).
`ai.batch.status`	`GET /v1/ai/batch/status/{id}`	Get a batch job's status, progress, and completed/failed counts.
`ai.batch.submit`	`POST /v1/ai/batch/submit`	Submit a batch of AI requests as one async batch job (billed at cost pass-through with no markup).
`ai.cost.compare`	`POST /v1/ai/cost/compare`	Estimate and compare the cost of the same request across multiple models.
`ai.cost.estimate`	`POST /v1/ai/cost/estimate`	Estimate token counts and itemized cost for an AI request before calling it.
`ai.image.upscale`	`POST /v1/ai/image/upscale`	Upscale an image losslessly by 2x or 4x with an AI model (idempotent). To transform an EXISTING image otherwise use the image.* module.
`ai.rerank`	`POST /v1/ai/rerank`	Reorder a list of candidate documents by relevance to a query, returning each candidate's original index and a vendor relevance score. Real vendor dispatch: Cohere rerank, Jina, Qwen/DashScope gte-rerank. Replaces the previous original-order mock.
`ai.tokens.count`	`POST /v1/ai/tokens/count`	Count input tokens for a set of messages under a given model.
`ai.tts.voices`	`GET /v1/ai/tts/voices`	List available text-to-speech voices with pagination.
`ai.voice.session`	`POST /v1/ai/voice/session`	Mint a short-lived token for an AI realtime VOICE/multimodal conversation session (e.g. OpenAI Realtime). NOT pub/sub channel auth — see realtime.token.issue.

完整示例

本模块的生产级端到端范例:先一次性配置,再运行业务流程,尽量覆盖本模块的多数 API。

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

# 1) Auth: every call is a raw HTTPS request to the Infrai gateway carrying
#    only your project key. No SDK, no install.
#    Get your key: sign in with Google/GitHub at the console for a project key
#    + $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
#    POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."   # from the console


# 2) ai.batch.submit
curl -X POST https://api.infrai.cc/v1/ai/batch/submit \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requests": []}'

# 3) ai.batch.status
curl -X GET https://api.infrai.cc/v1/ai/batch/status/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"