AI Runtime

Core LLM inference — chat, embeddings, vision, image generation, speech (TTS/ASR) — is OpenAI-compatible: call it with the official openai SDK pointed at the infrai base_url. The methods here are the infrai-native extensions: batch, cost/token tooling, rerank, image upscale, TTS voices and live voice sessions.

Overview

Base path: https://api.infrai.cc/v1/ai

Auth header: 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"

Methods

ai.batch.submit

POST /v1/ai/batch/submit

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

Parameters

Name	Type	Required	Description
`requests`	`BatchRequestItem[]`	Required	批处理请求条目数组，每条含 capability 与 body。
`batch_timeout`	`string`	Optional	批处理的最长完成时限（如 24h），超时未完成的条目按失败处理。
`metadata`	`Record<string, unknown>`	Optional	附加到批处理任务上的自定义键值元数据。
`idempotency_key`	`string`	Optional	Optional dedup key; identical retries return the same result.

Returns

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

Example

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

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}

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

Parameters

Name	Type	Required	Description
`batch_id`	`string`	Required	目标批处理任务的 ID。

Returns

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

Example

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

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}

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

Parameters

Name	Type	Required	Description
`batch_id`	`string`	Required	目标批处理任务的 ID。
`cursor`	`string`	Optional	分页游标：传入上一页返回的 next_cursor 获取下一页。
`limit`	`number`	Optional	单页返回条数上限。

Returns

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

Example

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

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

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

Parameters

Name	Type	Required	Description
`cursor`	`string`	Optional	分页游标：传入上一页返回的 next_cursor 获取下一页。
`limit`	`number`	Optional	单页返回条数上限。

Returns

BatchListResult { batches, total_count, next_cursor? }

Example

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

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}

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

Parameters

Name	Type	Required	Description
`batch_id`	`string`	Required	要取消的批处理任务的 ID。
`idempotency_key`	`string`	Optional	Optional dedup key; identical retries return the same result.

Returns

BatchStatus { batch_id, state, ... }

Example

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

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 文件并返回下载任务。

Parameters

Name	Type	Required	Description
`batch_id`	`string`	Required	要导出的批处理任务的 ID。
`format`	`"jsonl" \| "csv"`	Optional	导出文件格式：jsonl 或 csv。
`conversation_id`	`string`	Optional	可选，仅导出指定会话的结果。
`metadata`	`Record<string, unknown>`	Optional	附加到导出任务上的自定义键值元数据。
`idempotency_key`	`string`	Optional	Optional dedup key; identical retries return the same result.

Returns

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

Example

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

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}

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

Parameters

Name	Type	Required	Description
`batch_id`	`string`	Required	目标批处理任务的 ID。
`retention_days`	`number`	Required	结果保留天数，到期后自动删除。
`idempotency_key`	`string`	Optional	Optional dedup key; identical retries return the same result.

Returns

BatchStatus { batch_id, state, ... }

Example

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

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 数与分项成本。

Parameters

Name	Type	Required	Description
`messages`	`string \| ChatMessage[]`	Required	用于估算的消息，可为字符串或消息数组。
`model`	`string`	Optional	Explicit model id; skips task/prefer routing.
`expected_output_tokens`	`number`	Optional	预期的输出 token 数，用于估算输出侧成本。
`cache_strategy`	`"vendor" \| "infrai" \| "none"`	Optional	Which cache layer to use.
`batch_mode`	`boolean`	Optional	Run as a batch job for a discounted rate.
`tools`	`Tool[]`	Optional	Tool/function-calling definitions.

Returns

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

Example

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

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

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

Parameters

Name	Type	Required	Description
`messages`	`string \| ChatMessage[]`	Required	用于对比估算的消息，可为字符串或消息数组。
`models`	`string[]`	Optional	参与成本对比的模型 ID 列表。
`expected_output_tokens`	`number`	Optional	预期的输出 token 数，用于估算输出侧成本。
`cache_strategy`	`"vendor" \| "infrai" \| "none"`	Optional	Which cache layer to use.
`batch_mode`	`boolean`	Optional	Run as a batch job for a discounted rate.
`tools`	`Tool[]`	Optional	Tool/function-calling definitions.

Returns

{ estimates: CostEstimate[] }

Example

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

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 数。

Parameters

Name	Type	Required	Description
`messages`	`string \| ChatMessage[]`	Required	要统计 token 数的消息，可为字符串或消息数组。
`model`	`string`	Optional	Explicit model id; skips task/prefer routing.
`tools`	`Tool[]`	Optional	Tool/function-calling definitions.

Returns

TokenCountResult { prompt_tokens, model }

Example

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

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 倍无损放大。

Parameters

Name	Type	Required	Description
`image`	`string`	Required	待放大的源图片，URL 或 base64。
`factor`	`2 \| 4`	Optional	放大倍数，2 或 4。
`idempotency_key`	`string`	Optional	Optional dedup key; identical retries return the same result.

Returns

ImageUpscaleResult { image, original_size, new_size }

Example

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

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

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

Parameters

Name	Type	Required	Description
`cursor`	`string`	Optional	分页游标：传入上一页返回的 next_cursor 获取下一页。
`limit`	`number`	Optional	单页返回条数上限。

Returns

VoiceListResult { voices, total_count, next_cursor? }

Example

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

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"

All capabilities

Every routed capability in this module — the complete public REST contract. The methods above are the guided walkthrough; this index is the full reference.

Capability	Endpoint	Description
`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.

End-to-end example

A production-style walkthrough of this module: configure once, then run the flow. It exercises most of the module's APIs.

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

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"