公网 URL

公网隧道与可分享 URL，支持可选自定义域名。

概览

基础路径: https://api.infrai.cc/v1/public-url

鉴权头: Authorization: Bearer $INFRAI_API_KEY

bash

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

方法

public_url.create

POST /v1/public_url/create

创建公网 URL 或隧道，可选子域名与 TTL。

参数

名称	类型	必填	说明
`subdomain`	`string`	可选	请求的子域名。
`port`	`number`	可选	要暴露的本地端口。
`ttl_seconds`	`number`	可选	过期前的有效时长（秒）。
`idempotency_key`	`string`	可选	可选去重 key；相同重试将返回同一结果。

PublicUrlRecord { url_id, url, subdomain, state, 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/public_url/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "report.txt", "text": "hello world", "expires_in": "7d", "max_downloads": 100}'

public_url.claim

POST /v1/public_url/claim/{id}

将匿名公网 URL 认领到你的账户。

参数

名称	类型	必填	说明
`id`	`string`	必填	公网 URL 记录 id。

PublicUrlRecord

示例

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

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/public_url/claim/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "..."}'

public_url.get

GET /v1/public_url/get/{id}

按 id 获取公网 URL 记录。

参数

名称	类型	必填	说明
`id`	`string`	必填	公网 URL 记录 id。

PublicUrlRecord

示例

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

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/public_url/get/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

public_url.domain.create

POST /v1/public_url/domain/create

为公网 URL 绑定自定义域名。

DomainRecord

示例

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

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/public_url/domain/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "links.acme.com"}'

public_url.list

GET /v1/public_url/list

分页列出当前账户拥有的所有公开文件 URL

参数

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

Paginated<FileUrl> { items: FileUrl[], 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/public_url/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

public_url.update

PATCH /v1/public_url/update/{id}

更新公开文件 URL 的访问控制（密码、下载次数上限、IP/地区白名单、限流、标签等）

参数

名称	类型	必填	说明
`id`	`string`	必填	要更新的公开 URL 的 url_id
`password`	`string`	可选	访问密码；传 null 可清除已设置的密码
`max_downloads`	`number`	可选	允许的最大下载次数
`ip_allowlist`	`string[]`	可选	允许访问的 IP/CIDR 白名单
`geo_allowlist`	`string[]`	可选	允许访问的国家/地区代码白名单
`rate_limit_rps`	`number`	可选	每秒请求数限流上限（RPS）
`auth`	`object`	可选	鉴权配置对象（如 Bearer/Basic）
`label`	`string`	可选	便于识别的备注标签
`tags`	`Record<string, string>`	可选	自定义键值标签
`idempotency_key`	`string`	可选	幂等键，用于防止重试导致的重复写入

FileUrl

示例

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

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 PATCH https://api.infrai.cc/v1/public_url/update/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "..."}'

public_url.extend

POST /v1/public_url/extend/{id}

延长公开文件 URL 的有效期，按小时追加

参数

名称	类型	必填	说明
`id`	`string`	必填	要延长的公开 URL 的 url_id
`additional_hours`	`number`	必填	在当前到期时间基础上追加的小时数
`idempotency_key`	`string`	可选	幂等键，用于防止重试导致的重复延长

FileUrl

示例

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

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/public_url/extend/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "...", "additional_hours": 0}'

public_url.disable

POST /v1/public_url/disable/{id}

停用一个公开文件 URL，使其立即不可访问

参数

名称	类型	必填	说明
`id`	`string`	必填	要停用的公开 URL 的 url_id
`idempotency_key`	`string`	可选	幂等键，用于防止重试导致的重复操作

FileUrl

示例

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

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/public_url/disable/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

public_url.delete

DELETE /v1/public_url/delete/{id}

永久删除一个公开文件 URL

参数

名称	类型	必填	说明
`id`	`string`	必填	要删除的公开 URL 的 url_id
`idempotency_key`	`string`	可选	幂等键，用于防止重试导致的重复删除

void

示例

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

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 DELETE https://api.infrai.cc/v1/public_url/delete/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

public_url.stats

GET /v1/public_url/stats/{id}

查询公开文件 URL 的访问统计：带宽、请求数、延迟分位与状态码分布

参数

名称	类型	必填	说明
`id`	`string`	必填	要查询统计的公开 URL 的 url_id

UrlStats { url_id, period, bandwidth_used_gb, access_count, p99_latency_ms, 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 GET https://api.infrai.cc/v1/public_url/stats/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

public_url.events

GET /v1/public_url/events/{id}

分页查询公开文件 URL 的访问事件流

参数

名称	类型	必填	说明
`id`	`string`	必填	要查询事件的公开 URL 的 url_id
`cursor`	`string`	可选	分页游标，传入上一页返回的 next_cursor 以获取下一页
`limit`	`number`	可选	单页返回的最大事件数

Paginated<AccessEvent> { items: AccessEvent[], 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/public_url/events/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

public_url.retention.get

GET /v1/public_url/retention/get/{id}

查询公开文件 URL 的留存策略

参数

名称	类型	必填	说明
`id`	`string`	必填	要查询留存策略的公开 URL 的 url_id

RetentionPolicy { url_id, retention_days, delete_after }

示例

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

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/public_url/retention/get/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

public_url.retention.set

POST /v1/public_url/retention/set/{id}

设置公开文件 URL 的留存天数与到期删除策略

参数

名称	类型	必填	说明
`id`	`string`	必填	要设置留存策略的公开 URL 的 url_id
`retention_days`	`number`	必填	留存天数，到期后自动删除
`idempotency_key`	`string`	可选	幂等键，用于防止重试导致的重复设置

RetentionPolicy { url_id, retention_days, delete_after }

示例

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

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/public_url/retention/set/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "...", "days": 0}'

public_url.domain.get

GET /v1/public_url/domain/get/{domain}

查询单个自定义域名的状态、验证与证书信息

参数

名称	类型	必填	说明
`domain`	`string`	必填	要查询的自定义域名

Domain { domain, label, status, verified_at, cert_expires_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 GET https://api.infrai.cc/v1/public_url/domain/get/DOMAIN \
  -H "Authorization: Bearer $INFRAI_API_KEY"

public_url.domain.list

GET /v1/public_url/domain/list

分页列出账户已添加的自定义域名

参数

名称	类型	必填	说明
`cursor`	`string`	可选	分页游标，传入上一页返回的 next_cursor 以获取下一页
`limit`	`number`	可选	单页返回的最大域名数

Paginated<Domain> { items: Domain[], 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/public_url/domain/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

public_url.domain.verify

POST /v1/public_url/domain/verify

触发自定义域名的归属验证与证书签发

参数

名称	类型	必填	说明
`domain`	`string`	必填	要验证的自定义域名

VerifyResult { domain, verified, verified_at, cert_issuer, reason }

示例

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

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/public_url/domain/verify \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "links.acme.com"}'

public_url.domain.delete

DELETE /v1/public_url/domain/delete/{domain}

删除一个自定义域名

参数

名称	类型	必填	说明
`domain`	`string`	必填	要删除的自定义域名
`idempotency_key`	`string`	可选	幂等键，用于防止重试导致的重复删除

void

示例

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

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 DELETE https://api.infrai.cc/v1/public_url/domain/delete/DOMAIN \
  -H "Authorization: Bearer $INFRAI_API_KEY"

全部能力

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

能力	端点	说明
`public_url.claim`	`POST /v1/public_url/claim/{id}`	Claim an unbound (device-state) public URL onto the calling bound account; idempotent for URLs you already own.
`public_url.create`	`POST /v1/public_url/create`	Upload content and instantly get a public download URL with full access control in a single step.
`public_url.delete`	`DELETE /v1/public_url/delete/{id}`	Delete a public file URL permanently.
`public_url.disable`	`POST /v1/public_url/disable/{id}`	Disable a public file URL, making it immediately inaccessible.
`public_url.domain.create`	`POST /v1/public_url/domain/create`	Register a custom domain for hosting public URLs, returning the DNS records to publish (distinct from email sender domains — see email.domain.*).
`public_url.domain.delete`	`DELETE /v1/public_url/domain/delete/{domain}`	Delete a custom domain (distinct from email sender domains — see email.domain.*).
`public_url.domain.get`	`GET /v1/public_url/domain/get/{domain}`	Get a custom domain's status, verification, and certificate details (distinct from email sender domains — see email.domain.*).
`public_url.domain.list`	`GET /v1/public_url/domain/list`	List the account's custom domains with pagination (distinct from email sender domains — see email.domain.*).
`public_url.domain.verify`	`POST /v1/public_url/domain/verify`	Trigger ownership verification and certificate issuance for a custom domain (distinct from email sender domains — see email.domain.*).
`public_url.events`	`GET /v1/public_url/events/{id}`	List a public file URL's access-event stream (source IP/region/UA, status codes, lifecycle actions) with pagination.
`public_url.extend`	`POST /v1/public_url/extend/{id}`	Extend a public file URL's expiry by additional hours.
`public_url.get`	`GET /v1/public_url/get/{id}`	Retrieve a public URL's metadata and status by ID.
`public_url.list`	`GET /v1/public_url/list`	List all public file URLs owned by the account with pagination.
`public_url.retention.get`	`GET /v1/public_url/retention/get/{id}`	Get the retention policy for public file URLs.
`public_url.retention.set`	`POST /v1/public_url/retention/set/{id}`	Set the retention days and expiry-deletion policy for public file URLs.
`public_url.stats`	`GET /v1/public_url/stats/{id}`	Query public file URL access statistics: bandwidth, request count, latency percentiles, and status-code distribution.
`public_url.update`	`PATCH /v1/public_url/update/{id}`	Update a public file URL's access controls: password, max-downloads, IP/geo allowlists.

完整示例

本模块的生产级端到端范例:先一次性配置,再运行业务流程,尽量覆盖本模块的多数 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) public_url.create
curl -X POST https://api.infrai.cc/v1/public_url/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "report.txt", "text": "hello world", "expires_in": "7d", "max_downloads": 100}'

# 3) public_url.claim
curl -X POST https://api.infrai.cc/v1/public_url/claim/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "..."}'

# 4) public_url.get
curl -X GET https://api.infrai.cc/v1/public_url/get/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

# 5) public_url.domain.create
curl -X POST https://api.infrai.cc/v1/public_url/domain/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "links.acme.com"}'

# 6) public_url.list
curl -X GET https://api.infrai.cc/v1/public_url/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

# 7) public_url.update
curl -X PATCH https://api.infrai.cc/v1/public_url/update/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "..."}'

# 8) public_url.extend
curl -X POST https://api.infrai.cc/v1/public_url/extend/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "...", "additional_hours": 0}'

# 9) public_url.disable
curl -X POST https://api.infrai.cc/v1/public_url/disable/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'