# info.summary
TikTok commerce-content publishing, creator analysis data, AI media generation, AI model APIs, viral-video replication, and public content data APIs.

# info.description
Use the LINGTU AI OpenAPI to query authorized creators and TikTok Shop products, upload media, create TikTok Shop video or photo publishing tasks, generate AI images and videos, fetch TikTok and Instagram creator post data, relay supported AI models, stream viral-video replication prompts, and fetch public content metrics.  A JSON request succeeds only when the HTTP status is successful and the response body has `code: 0`. Streaming replication requests and chat completions with `stream: true` return `text/event-stream` on success.

# tags[].description
Authorized creators, TikTok Shop products, and publishing tasks.

# tags[].description
Presigned media upload and confirmation.

# tags[].description
Create and query scheduled AI image and video generation tasks.

# tags[].description
Stream a replication prompt from a public video URL or an uploaded file.

# tags[].description
OpenAI-compatible access to supported text and vision models.

# tags[].description
Public TikTok and Instagram creator profiles and recent posts for analysis workflows.

# paths./v1/creatorAccount/tiktokShopOauth/authorize.get.summary
Create a TikTok Shop creator authorization URL

# paths./v1/creatorAccount/tiktokShopOauth/authorize.get.description
Creates a TikTok Shop OAuth authorization URL for the selected market and shop type. Open the returned URL in a browser or render it as a QR code, then complete authorization in TikTok Shop.

# paths./v1/creatorAccount/tiktokShopOauth/authorize.get.parameters[].description
TikTok Shop authorization market and shop type. Values ending in _local are local shops; values ending in _cross are cross-border shops.

# paths./v1/creatorAccount/tiktokShopOauth/authorize.get.responses.403.description
The API key does not have permission for this operation.

# paths./v1/creatorAccount/tiktokShopOauth/authorize.get.responses.429.description
Too many requests. Retry with exponential backoff.

# paths./v1/creatorAccount/tiktokShopOauth/authorize.get.responses.429.headers.Retry-After.description
Seconds to wait before retrying, when provided.

# paths./v1/creatorAccount/tiktokShopOauth/authorize.get.responses.500.description
Unexpected server error. Retry transient failures with exponential backoff.

# paths./v1/creatorAccount/tiktokShopOauth/authorize.get.x-ui.summary
按目标市场和店铺类型生成 TikTok Shop 达人授权地址。将响应中的 url 在浏览器打开或生成二维码，引导达人完成授权。

# paths./v1/creatorAccount/tiktokShopOauth/authorize.get.x-ui.summaryEn
Create a TikTok Shop creator authorization URL for a market and shop type. Open the returned url in a browser or render it as a QR code for the creator.

# paths./v1/creatorAccount/tiktokShopOauth/authorize.get.x-ui.parameters[].type
us_cross | us_local | br_local | br_cross | mx_local | mx_cross | gb_local | de_local | de_cross | fr_local | fr_cross | es_local | es_cross | it_local | it_cross | ie_local | ie_cross | jp_local | jp_cross | th_local | th_cross | my_local | my_cross | id_local | id_cross | sg_local | sg_cross | vn_local | vn_cross | ph_local | ph_cross

# paths./v1/creatorAccount/tiktokShopOauth/authorize.get.x-ui.parameters[].description
授权地区与店铺类型；_local 表示本土店，_cross 表示跨境店

# paths./v1/creatorAccount/tiktokShopOauth/authorize.get.x-ui.parameters[].descriptionEn
Authorization market and shop type; _local means local shop and _cross means cross-border shop

# paths./v1/creatorAccount/tiktokShopOauth/authorize.get.x-ui.notes[]
英国跨境授权已下线，仅支持 gb_local。

# paths./v1/creatorAccount/tiktokShopOauth/authorize.get.x-ui.notes[]
授权地址应由服务端使用 API Key 获取；不要将 API Key 暴露在浏览器代码中。

# paths./v1/creatorAccount/tiktokShopOauth/authorize.get.x-ui.notesEn[]
Use us_cross for US cross-border shops and us_local for US local or ACCU shops.

# paths./v1/creatorAccount/tiktokShopOauth/authorize.get.x-ui.notesEn[]
UK cross-border authorization is no longer available; use gb_local only.

# paths./v1/creatorAccount/tiktokShopOauth/authorize.get.x-ui.notesEn[]
Request the URL from your server with the API key; never expose the API key in browser code.

# paths./v1/creatorAccount/pageList.get.description
Returns authorized creator accounts and publishing permissions. Use `id` for product queries and `creatorId` when creating publishing tasks.

# paths./v1/creatorAccount/pageList.get.parameters[].description
Authorization source. Use TIKTOK_SHOP_CREATOR for commerce publishing.

# paths./v1/creatorAccount/pageList.get.parameters[].description
TikTok usernames. Repeat the query parameter for multiple values.

# paths./v1/creatorAccount/pageList.get.parameters[].description
Return accounts with shoppable photo permission only.

# paths./v1/creatorAccount/pageList.get.responses.403.description
The API key does not have permission for this operation.

# paths./v1/creatorAccount/pageList.get.responses.429.description
Too many requests. Retry with exponential backoff.

# paths./v1/creatorAccount/pageList.get.responses.429.headers.Retry-After.description
Seconds to wait before retrying, when provided.

# paths./v1/creatorAccount/pageList.get.responses.500.description
Unexpected server error. Retry transient failures with exponential backoff.

# paths./v1/creatorAccount/pageList.get.x-ui.summary
查询 TikTok Shop 已授权达人、目标地区和发布权限。响应中的 id 用于查商品，creatorId 用于创建发布任务。

# paths./v1/creatorAccount/pageList.get.x-ui.summaryEn
List authorized TikTok Shop creators, regions, and posting permissions. Use id for product queries and creatorId when creating a post.

# paths./v1/creatorAccount/pageList.get.x-ui.parameters[].description
是否只返回有效授权，默认 true

# paths./v1/creatorAccount/pageList.get.x-ui.parameters[].descriptionEn
Return valid authorizations only; defaults to true

# paths./v1/creatorAccount/pageList.get.x-ui.parameters[].descriptionEn
Use TIKTOK_SHOP_CREATOR for commerce posts

# paths./v1/creatorAccount/pageList.get.x-ui.parameters[].description
重复 Query 参数传递多个用户名

# paths./v1/creatorAccount/pageList.get.x-ui.parameters[].descriptionEn
Repeat the query parameter for multiple usernames

# paths./v1/creatorAccount/pageList.get.x-ui.parameters[].description
仅返回有带货图文权限的账号

# paths./v1/creatorAccount/pageList.get.x-ui.parameters[].descriptionEn
Return accounts with shoppable photo permission only

# paths./v1/creator/tiktokshop/product/listByShowcase.get.description
Lists products in a creator showcase. Use `SHOWCASE` as the product source when creating a publishing task.

# paths./v1/creator/tiktokshop/product/listByShowcase.get.parameters[].description
Pagination token from the previous response.

# paths./v1/creator/tiktokshop/product/listByShowcase.get.responses.403.description
The API key does not have permission for this operation.

# paths./v1/creator/tiktokshop/product/listByShowcase.get.responses.429.description
Too many requests. Retry with exponential backoff.

# paths./v1/creator/tiktokshop/product/listByShowcase.get.responses.429.headers.Retry-After.description
Seconds to wait before retrying, when provided.

# paths./v1/creator/tiktokshop/product/listByShowcase.get.responses.500.description
Unexpected server error. Retry transient failures with exponential backoff.

# paths./v1/creator/tiktokshop/product/listByShowcase.get.x-ui.summary
查询达人橱窗商品。创建发布任务时，商品来源 source 应传 SHOWCASE。

# paths./v1/creator/tiktokshop/product/listByShowcase.get.x-ui.summaryEn
List products in a creator showcase. Use SHOWCASE as the product source when creating a post.

# paths./v1/creator/tiktokshop/product/listByShowcase.get.x-ui.parameters[].description
上一页返回的分页 Token

# paths./v1/creator/tiktokshop/product/listByShowcase.get.x-ui.parameters[].descriptionEn
Pagination token from the previous response

# paths./v1/creator/tiktokshop/product/listByShowcase.get.x-ui.notes[]
该接口不接收 titleKeyword；如需搜索，请在客户端按 title 过滤。

# paths./v1/creator/tiktokshop/product/listByShowcase.get.x-ui.notesEn[]
This endpoint does not accept titleKeyword. Filter by title on the client when needed.

# paths./v1/creator/tiktokshop/product/addToShowcase.post.description
Adds TikTok Shop products to an authorized creator showcase. Use PRODUCT_ID with 1–20 productIds, or PRODUCT_LINK with productLink. A response with code 0 can still contain data.errors when some products failed to be added. The creator authorization must include creator.showcase.write and creator.video.write.

# paths./v1/creator/tiktokshop/product/addToShowcase.post.responses.200.description
Request processed. Inspect code and data.errors because individual products can fail even when code is 0.

# paths./v1/creator/tiktokshop/product/addToShowcase.post.responses.403.description
The API key does not have permission for this operation.

# paths./v1/creator/tiktokshop/product/addToShowcase.post.responses.429.description
Too many requests. Retry with exponential backoff.

# paths./v1/creator/tiktokshop/product/addToShowcase.post.responses.429.headers.Retry-After.description
Seconds to wait before retrying, when provided.

# paths./v1/creator/tiktokshop/product/addToShowcase.post.responses.500.description
Unexpected server error. Retry transient failures with exponential backoff.

# paths./v1/creator/tiktokshop/product/addToShowcase.post.x-ui.title
创作者TTS-添加橱窗商品

# paths./v1/creator/tiktokshop/product/addToShowcase.post.x-ui.summary
将 TikTok Shop 商品添加到创作者展示橱窗。可按商品 ID 批量添加，或通过单个商品链接添加。

# paths./v1/creator/tiktokshop/product/addToShowcase.post.x-ui.summaryEn
Add TikTok Shop products to an authorized creator showcase by product IDs or a product link.

# paths./v1/creator/tiktokshop/product/addToShowcase.post.x-ui.parameters[].descriptionEn
Required for PRODUCT_ID; 1–20 product IDs

# paths./v1/creator/tiktokshop/product/addToShowcase.post.x-ui.notes[]
业务 code=0 时仍需检查 data.errors；存在 errors 表示对应商品添加失败。

# paths./v1/creator/tiktokshop/product/addToShowcase.post.x-ui.notes[]
创作者授权失效时返回业务错误「授权过期，请重新授权」。

# paths./v1/creator/tiktokshop/product/addToShowcase.post.x-ui.notesEn[]
A request can contain at most 20 product IDs.

# paths./v1/creator/tiktokshop/product/addToShowcase.post.x-ui.notesEn[]
Check data.errors even when code is 0; entries identify products that failed.

# paths./v1/creator/tiktokshop/product/addToShowcase.post.x-ui.notesEn[]
An expired creator authorization returns the business error “授权过期，请重新授权”.

# paths./v1/file/presign.post.description
Returns a file ID and a presigned object-storage URL. When `isNew` is false, skip PUT and confirmation. When `isNew` is true, PUT the raw file bytes to `uploadUrl` with the same Content-Type, without the x-api-key header, then confirm the upload.

# paths./v1/file/presign.post.responses.403.description
The API key does not have permission for this operation.

# paths./v1/file/presign.post.responses.429.description
Too many requests. Retry with exponential backoff.

# paths./v1/file/presign.post.responses.429.headers.Retry-After.description
Seconds to wait before retrying, when provided.

# paths./v1/file/presign.post.responses.500.description
Unexpected server error. Retry transient failures with exponential backoff.

# paths./v1/file/presign.post.x-ui.summary
提交文件信息和兼容 Hash，获取 fileId 与对象存储上传地址。isNew=false 表示文件已存在，可跳过上传和确认。

# paths./v1/file/presign.post.x-ui.summaryEn
Submit file metadata and the compatible hash to receive a fileId and object-storage URL. Skip upload and confirmation when isNew is false.

# paths./v1/file/presign.post.x-ui.parameters[].descriptionEn
SHA-256 of the UTF-8 encoded lowercase hex representation of the file bytes

# paths./v1/file/presign.post.x-ui.notes[]
isNew=true 时，使用相同 Content-Type 将原始文件 PUT 到 uploadUrl，成功后再调用 confirm。

# paths./v1/file/presign.post.x-ui.notesEn[]
When isNew is true, PUT the raw file to uploadUrl with the same Content-Type, then call confirm.

# paths./v1/file/presign.post.x-ui.notesEn[]
Do not send x-api-key to the object-storage PUT URL.

# paths./v1/file/confirm.post.description
Call only after a new file is successfully uploaded to its presigned URL. Deduplicated files do not require confirmation.

# paths./v1/file/confirm.post.responses.403.description
The API key does not have permission for this operation.

# paths./v1/file/confirm.post.responses.429.description
Too many requests. Retry with exponential backoff.

# paths./v1/file/confirm.post.responses.429.headers.Retry-After.description
Seconds to wait before retrying, when provided.

# paths./v1/file/confirm.post.responses.500.description
Unexpected server error. Retry transient failures with exponential backoff.

# paths./v1/file/confirm.post.x-ui.summary
仅在新文件成功 PUT 到预签名地址后调用。秒传文件不需要确认。

# paths./v1/file/confirm.post.x-ui.summaryEn
Call only after a new file is successfully PUT to its presigned URL. Deduplicated files do not require confirmation.

# paths./v1/file/confirm.post.x-ui.parameters[].description
预签名接口返回的文件 ID

# paths./v1/file/confirm.post.x-ui.parameters[].descriptionEn
File ID returned by the presign endpoint

# paths./v1/creator/post/create.post.description
Creates a TikTok Shop commerce video or photo publishing task. A successful response means the task was accepted, not that TikTok publishing has completed.

# paths./v1/creator/post/create.post.responses.403.description
The API key does not have permission for this operation.

# paths./v1/creator/post/create.post.responses.429.description
Too many requests. Retry with exponential backoff.

# paths./v1/creator/post/create.post.responses.429.headers.Retry-After.description
Seconds to wait before retrying, when provided.

# paths./v1/creator/post/create.post.responses.500.description
Unexpected server error. Retry transient failures with exponential backoff.

# paths./v1/creator/post/create.post.x-ui.summary
创建 TikTok Shop 带货视频或带货图文发布任务。请求成功仅表示任务已接收，最终结果请在发布记录中确认。

# paths./v1/creator/post/create.post.x-ui.summaryEn
Create a TikTok Shop commerce video or photo publishing task. A successful response means the task was accepted; verify the final result in publishing records.

# paths./v1/creator/post/create.post.x-ui.parameters[].descriptionEn
Video fileId; first image fileId for photo posts

# paths./v1/creator/post/create.post.x-ui.parameters[].description
上传文件固定传 FILE

# paths./v1/creator/post/create.post.x-ui.parameters[].descriptionEn
creatorId returned by the creator endpoint

# paths./v1/creator/post/create.post.x-ui.parameters[].description
发布文案，最长 4000 字符

# paths./v1/creator/post/create.post.x-ui.parameters[].descriptionEn
Custom video cover file ID; pass together with tiktokShop.coverUri and omit for photo posts

# paths./v1/creator/post/create.post.x-ui.parameters[].description
VIDEO 时必填，包含商品、封面、预审、音乐和 AI 标识

# paths./v1/creator/post/create.post.x-ui.parameters[].descriptionEn
Required for VIDEO; contains product, cover, pre-check, music, and AI label options

# paths./v1/creator/post/create.post.x-ui.parameters[].description
是否在发布前提交预审，默认 false

# paths./v1/creator/post/create.post.x-ui.parameters[].descriptionEn
Whether to submit a pre-check before publishing; defaults to false

# paths./v1/creator/post/create.post.x-ui.parameters[].description
是否标识为 AI 生成内容；为 true 时 TikTok 会添加“AI 生成”标签

# paths./v1/creator/post/create.post.x-ui.parameters[].descriptionEn
Whether to label the video as AI-generated; TikTok adds an AI-generated label when true

# paths./v1/creator/post/create.post.x-ui.parameters[].descriptionEn
URI returned by the cover upload endpoint; pass coverFileId with it

# paths./v1/creator/post/create.post.x-ui.parameters[].description
从视频指定毫秒位置截帧作为封面；有 coverUri 时不传

# paths./v1/creator/post/create.post.x-ui.parameters[].descriptionEn
Video timestamp in milliseconds to use as the cover frame; omit when coverUri is present

# paths./v1/creator/post/create.post.x-ui.parameters[].description
视频背景音乐；不需要音乐时不传

# paths./v1/creator/post/create.post.x-ui.parameters[].descriptionEn
Video background music; omit when no music is needed

# paths./v1/creator/post/create.post.x-ui.parameters[].descriptionEn
Music ID, required when musicInfo is provided

# paths./v1/creator/post/create.post.x-ui.parameters[].description
VIDEO 时必填；商品接口返回的商品 ID

# paths./v1/creator/post/create.post.x-ui.parameters[].descriptionEn
Required for VIDEO; product ID returned by the product endpoint

# paths./v1/creator/post/create.post.x-ui.parameters[].description
VIDEO 时必填；购物车展示标题，最长 30 字符

# paths./v1/creator/post/create.post.x-ui.parameters[].descriptionEn
Required for VIDEO; product anchor title, up to 30 characters

# paths./v1/creator/post/create.post.x-ui.parameters[].descriptionEn
Required for VIDEO; SHOP for shop products or SHOWCASE for showcase products

# paths./v1/creator/post/create.post.x-ui.parameters[].description
PHOTO 时必填；1～15 个图片 fileId，按最终展示顺序排列

# paths./v1/creator/post/create.post.x-ui.parameters[].descriptionEn
Required for PHOTO; 1–15 image fileIds in final display order

# paths./v1/creator/post/create.post.x-ui.parameters[].description
PHOTO 时必填；唯一挂车商品的商品 ID

# paths./v1/creator/post/create.post.x-ui.parameters[].descriptionEn
Required for PHOTO; product ID for the single product anchor

# paths./v1/creator/post/create.post.x-ui.parameters[].description
PHOTO 时必填；购物车展示标题，最长 30 字符

# paths./v1/creator/post/create.post.x-ui.parameters[].descriptionEn
Required for PHOTO; product anchor title, up to 30 characters

# paths./v1/creator/post/create.post.x-ui.parameters[].description
PHOTO 时必填；商品来源

# paths./v1/creator/post/create.post.x-ui.parameters[].description
图文背景音乐；不需要音乐时不传

# paths./v1/creator/post/create.post.x-ui.parameters[].descriptionEn
Photo post background music; omit when no music is needed

# paths./v1/creator/post/create.post.x-ui.parameters[].descriptionEn
Music ID, required when musicInfo is provided

# paths./v1/creator/post/create.post.x-ui.notes[]
图文支持 1～15 张图片和 1 个商品；businessId 必须等于 businessIds[0]，首图即封面。

# paths./v1/creator/post/create.post.x-ui.notes[]
保存 postId 和 status，并前往发布记录确认最终状态。

# paths./v1/creator/post/create.post.x-ui.notesEn[]
For a video cover, use tiktokShop.coverTimestampMs for a frame or pass coverFileId together with tiktokShop.coverUri for a custom cover; do not mix the two methods.

# paths./v1/creator/post/create.post.x-ui.notesEn[]
Photo posts support 1–15 images and one product; businessId must equal businessIds[0], and the first image is the cover.

# paths./v1/creator/post/create.post.x-ui.notesEn[]
Persist postId and status, then verify the final state in publishing records.

# paths./v1/creator/post/pageList.get.description
Returns paginated TikTok and TikTok Shop publishing records. Use this endpoint after creating a publishing task to confirm its current or final status and read platform post identifiers, failure reasons, media, product, and scheduling information.

# paths./v1/creator/post/pageList.get.parameters[].description
Account manager IDs. Repeat the query parameter for multiple values.

# paths./v1/creator/post/pageList.get.parameters[].description
Return records for accounts without an assigned manager only.

# paths./v1/creator/post/pageList.get.responses.403.description
The API key does not have permission for this operation.

# paths./v1/creator/post/pageList.get.responses.429.description
Too many requests. Retry with exponential backoff.

# paths./v1/creator/post/pageList.get.responses.429.headers.Retry-After.description
Seconds to wait before retrying, when provided.

# paths./v1/creator/post/pageList.get.responses.500.description
Unexpected server error. Retry transient failures with exponential backoff.

# paths./v1/creator/post/pageList.get.x-ui.summary
分页查询 TikTok 与 TikTok Shop 发布记录，用于跟踪任务状态，并读取平台作品 ID、失败原因、素材、商品和排期信息。

# paths./v1/creator/post/pageList.get.x-ui.summaryEn
List paginated TikTok and TikTok Shop publishing records to track status and read platform post IDs, failure reasons, media, product, and scheduling details.

# paths./v1/creator/post/pageList.get.x-ui.parameters[].type
WAITING_SUBMIT | SUBMITTING | PRE_CHECK_SUBMITTING | PRE_CHECK | PRE_CHECK_PASSED | PRE_CHECK_REJECTED | PENDING | PROCESSING | SUCCESS | COMPLETED | FAILED | CANCELLED | SUBMIT_FAILED

# paths./v1/creator/post/pageList.get.x-ui.parameters[].description
账号管理人 ID；多个值重复传递 Query 参数

# paths./v1/creator/post/pageList.get.x-ui.parameters[].descriptionEn
Account manager IDs; repeat the query parameter for multiple values

# paths./v1/creator/post/pageList.get.x-ui.parameters[].description
是否仅查询未分配管理人的账号

# paths./v1/creator/post/pageList.get.x-ui.parameters[].descriptionEn
Return accounts without an assigned manager only

# paths./v1/creator/post/pageList.get.x-ui.notes[]
发布创建成功不代表平台发布完成；请保存 postId，并通过本接口查询最终状态。

# paths./v1/creator/post/pageList.get.x-ui.notesEn[]
The minimal request only needs pageSize and pageNumber, for example ?pageSize=10&pageNumber=1.

# paths./v1/creator/post/pageList.get.x-ui.notesEn[]
Task creation does not mean platform publishing is complete. Persist postId and use this endpoint to verify the final status.

# paths./v1/creator/post/pageList.get.x-ui.notesEn[]
SUCCESS, COMPLETED, and PRE_CHECK_PASSED are success-like states; FAILED, SUBMIT_FAILED, and PRE_CHECK_REJECTED are failure-like states.

# paths./v1/ai/schedule/create.post.description
Creates one or more AI image or video generation tasks. Use the returned scheduleId to query task status and generated assets. Keep polling the same schedule until every requested output succeeds or explicitly fails.

# paths./v1/ai/schedule/create.post.requestBody.content.application/json.examples.image.value.params.prompt
A clean product hero image on a bright studio background

# paths./v1/ai/schedule/create.post.requestBody.content.application/json.examples.video.value.params.prompt
A clean 10-second product reveal video with a slow camera push-in

# paths./v1/ai/schedule/create.post.responses.200.links.generationTasks.description
Poll the tasks created for this schedule.

# paths./v1/ai/schedule/create.post.responses.403.description
The API key does not have permission for this operation.

# paths./v1/ai/schedule/create.post.responses.429.description
Too many requests. Retry with exponential backoff.

# paths./v1/ai/schedule/create.post.responses.429.headers.Retry-After.description
Seconds to wait before retrying, when provided.

# paths./v1/ai/schedule/create.post.responses.500.description
Unexpected server error. Retry transient failures with exponential backoff.

# paths./v1/ai/schedule/create.post.x-ui.title
创建 AI 图片或视频生成任务

# paths./v1/ai/schedule/create.post.x-ui.summary
创建 AI 图片或视频生成计划，支持提示词、参考图、模型、尺寸和批量数量。使用响应中的 scheduleId 查询任务状态与生成结果。

# paths./v1/ai/schedule/create.post.x-ui.summaryEn
Create scheduled AI image or video generation tasks with prompts, references, model options, dimensions, and output count. Use the returned scheduleId to query status and assets.

# paths./v1/ai/schedule/create.post.x-ui.parameters[].description
调用方生成的任务标识；建议使用 8 位小写字母或数字

# paths./v1/ai/schedule/create.post.x-ui.parameters[].descriptionEn
Caller-generated task identifier; an 8-character lowercase alphanumeric value is recommended

# paths./v1/ai/schedule/create.post.x-ui.parameters[].type
gpt-image-2 | nano-banana-2 | nano-banana-2-2k | nano-banana-2-4k | seedream5.0-lite | gemini-omni-video | veo3.1-lite-extend | veo3.1-extend | grok-imagine-1.5 | seedance2.0-mini | seedance2.0 | seedance2.0-fast

# paths./v1/ai/schedule/create.post.x-ui.parameters[].description
根据 type 选择下方列出的图片或视频模型

# paths./v1/ai/schedule/create.post.x-ui.parameters[].descriptionEn
Select one of the image or video models listed below, matching type

# paths./v1/ai/schedule/create.post.x-ui.parameters[].descriptionEn
Required for images, for example 1:1 or 9:16

# paths./v1/ai/schedule/create.post.x-ui.parameters[].description
视频生成时长；可选值取决于模型

# paths./v1/ai/schedule/create.post.x-ui.parameters[].descriptionEn
Video duration; allowed values depend on the model

# paths./v1/ai/schedule/create.post.x-ui.parameters[].description
单张远程参考图 URL，主要用于视频生成

# paths./v1/ai/schedule/create.post.x-ui.parameters[].descriptionEn
One remote reference image URL, primarily for video generation

# paths./v1/ai/schedule/create.post.x-ui.parameters[].description
按顺序传入的远程参考图 URL；不支持 data URL

# paths./v1/ai/schedule/create.post.x-ui.parameters[].descriptionEn
Ordered remote reference image URLs; data URLs are not supported

# paths./v1/ai/schedule/create.post.x-ui.parameters[].description
视频是否添加水印，默认 false

# paths./v1/ai/schedule/create.post.x-ui.parameters[].descriptionEn
Whether to add a video watermark; defaults to false

# paths./v1/ai/schedule/create.post.x-ui.parameters[].description
生成数量，未指定多结果时建议传 1

# paths./v1/ai/schedule/create.post.x-ui.parameters[].descriptionEn
Number of outputs; use 1 unless multiple results are needed

# paths./v1/ai/schedule/create.post.x-ui.parameters[].description
需要关联的业务对象 ID

# paths./v1/ai/schedule/create.post.x-ui.parameters[].description
ISO 8601 执行时间；省略时立即创建

# paths./v1/ai/schedule/create.post.x-ui.parameters[].descriptionEn
ISO 8601 execution time; omit to create immediately

# paths./v1/ai/schedule/create.post.x-ui.parameters[].descriptionEn
Display name for the generation schedule

# paths./v1/ai/schedule/create.post.x-ui.requestExamples.image.params.prompt
A clean product hero image on a bright studio background

# paths./v1/ai/schedule/create.post.x-ui.requestExamples.video.params.prompt
A clean 10-second product reveal video with a slow camera push-in

# paths./v1/ai/schedule/create.post.x-ui.notes[]
参考图必须是可访问的 http/https URL；本地文件需先上传后再传入 URL。

# paths./v1/ai/schedule/create.post.x-ui.notes[]
scheduleId 与 taskId 不同。创建成功后请使用 scheduleId 查询本计划的任务列表，不要因轮询中断而重复创建。

# paths./v1/ai/schedule/create.post.x-ui.notesEn[]
Video durations: gemini-omni-video supports 6/8/10s; veo3.1-lite-extend and veo3.1-extend are fixed at 8s; grok-imagine-1.5 supports 6/10/15/20/25/30s; seedance2.0-mini, seedance2.0, and seedance2.0-fast support 4/8/10/12/15s.

# paths./v1/ai/schedule/create.post.x-ui.notesEn[]
For images, use IMAGE_GENERATION with params.aspectRatio. For videos, use VIDEO_GENERATION with params.seconds and params.size.

# paths./v1/ai/schedule/create.post.x-ui.notesEn[]
References must be accessible http/https URLs. Upload local files before passing their URLs.

# paths./v1/ai/schedule/create.post.x-ui.notesEn[]
scheduleId and taskId are different. Query the same scheduleId after creation and do not recreate a task only because polling was interrupted.

# paths./v1/ai/task/listByScheduleId.get.description
Returns AI image or video generation tasks for one schedule. Poll this endpoint until the requested tasks reach a terminal status and expose their generated asset URLs.

# paths./v1/ai/task/listByScheduleId.get.parameters[].description
Schedule ID returned by the schedule creation endpoint.

# paths./v1/ai/task/listByScheduleId.get.responses.200.content.application/json.example.data.list[].params.prompt
A clean 10-second product reveal video with a slow camera push-in

# paths./v1/ai/task/listByScheduleId.get.responses.403.description
The API key does not have permission for this operation.

# paths./v1/ai/task/listByScheduleId.get.responses.429.description
Too many requests. Retry with exponential backoff.

# paths./v1/ai/task/listByScheduleId.get.responses.429.headers.Retry-After.description
Seconds to wait before retrying, when provided.

# paths./v1/ai/task/listByScheduleId.get.responses.500.description
Unexpected server error. Retry transient failures with exponential backoff.

# paths./v1/ai/task/listByScheduleId.get.x-ui.title
查询 AI 生成任务结果

# paths./v1/ai/task/listByScheduleId.get.x-ui.summary
使用创建接口返回的 scheduleId 查询本次图片或视频生成任务。建议每 5 秒轮询，直到任务完成或明确失败。

# paths./v1/ai/task/listByScheduleId.get.x-ui.summaryEn
List image or video generation tasks using the scheduleId returned at creation. Poll about every five seconds until tasks complete or explicitly fail.

# paths./v1/ai/task/listByScheduleId.get.x-ui.parameters[].descriptionEn
scheduleId returned when the generation schedule was created

# paths./v1/ai/task/listByScheduleId.get.x-ui.responseExample.data.list[].params.prompt
A clean 10-second product reveal video with a slow camera push-in

# paths./v1/ai/task/listByScheduleId.get.x-ui.notes[]
失败、取消或过期后再决定是否重试；网络错误或轮询进程退出不表示生成任务失败。

# paths./v1/ai/task/listByScheduleId.get.x-ui.notes[]
视频优先读取 customResult.videoUrl 或 result.url；图片通常读取 result.url 或 resultUrl。

# paths./v1/ai/task/listByScheduleId.get.x-ui.notesEn[]
Waiting states include WAITING_SUBMIT, SUBMITTING, PENDING, and PROCESSING. COMPLETED is successful.

# paths./v1/ai/task/listByScheduleId.get.x-ui.notesEn[]
Retry only after an explicit failure, cancellation, or expiration. A network or polling-process error does not mean generation failed.

# paths./v1/ai/task/listByScheduleId.get.x-ui.notesEn[]
For videos, prefer customResult.videoUrl or result.url. Images usually use result.url or resultUrl.

# paths./v1/influencer/fetchPosts.get.summary
Fetch a TikTok creator profile and recent posts

# paths./v1/influencer/fetchPosts.get.description
Returns a public TikTok creator profile and recent posts with views and engagement metrics. Use the response as evidence for creator monitoring, benchmarking, or an AI-generated analysis report.

# paths./v1/influencer/fetchPosts.get.parameters[].description
TikTok creator username without the leading @.

# paths./v1/influencer/fetchPosts.get.responses.200.description
Creator data returned successfully. A business response with code -1 means no public creator posts were available.

# paths./v1/influencer/fetchPosts.get.responses.403.description
The API key does not have permission for this operation.

# paths./v1/influencer/fetchPosts.get.responses.429.description
Too many requests. Retry with exponential backoff.

# paths./v1/influencer/fetchPosts.get.responses.429.headers.Retry-After.description
Seconds to wait before retrying, when provided.

# paths./v1/influencer/fetchPosts.get.responses.500.description
Unexpected server error. Retry transient failures with exponential backoff.

# paths./v1/influencer/fetchPosts.get.x-ui.summary
按 TikTok 达人 uniqueId 获取公开账号信息及近期作品的播放、点赞、评论、分享和收藏数据，可用于达人分析与监控。

# paths./v1/influencer/fetchPosts.get.x-ui.summaryEn
Fetch a public TikTok creator profile and recent post views, likes, comments, shares, and saves for creator analysis or monitoring.

# paths./v1/influencer/fetchPosts.get.x-ui.parameters[].description
TikTok 达人用户名，不含开头的 @

# paths./v1/influencer/fetchPosts.get.x-ui.parameters[].descriptionEn
TikTok creator username without the leading @

# paths./v1/influencer/fetchPosts.get.x-ui.parameters[].description
返回的近期作品数量，默认 40

# paths./v1/influencer/fetchPosts.get.x-ui.parameters[].descriptionEn
Number of recent posts to return; defaults to 40

# paths./v1/influencer/fetchPosts.get.x-ui.notes[]
该接口当前用于 TikTok 达人数据；不要通过同名用户名推断其他平台账号。

# paths./v1/influencer/fetchPosts.get.x-ui.notes[]
HTTP 200 且 code=0 才表示成功；code=-1 表示未获取到公开达人作品数据。

# paths./v1/influencer/fetchPosts.get.x-ui.notesEn[]
This operation currently returns TikTok creator data. Do not infer accounts on other platforms from matching usernames.

# paths./v1/influencer/fetchPosts.get.x-ui.notesEn[]
Treat the request as successful only when HTTP is 200 and code is 0. code -1 means no public creator posts were available.

# paths./v1/influencer/fetchPosts.get.x-ui.notesEn[]
To generate an AI creator report, turn this response into evidence and send it to /v1/relay/chat/completions.

# paths./v1/influencer/ins/fetchPosts.get.summary
Fetch an Instagram creator profile and recent posts

# paths./v1/influencer/ins/fetchPosts.get.description
Returns a public Instagram creator profile and recent posts. Some list results, especially image or carousel posts, can omit video views or engagement fields.

# paths./v1/influencer/ins/fetchPosts.get.parameters[].description
Instagram username without the leading @.

# paths./v1/influencer/ins/fetchPosts.get.responses.200.description
Creator data returned successfully. A business response with code -1 means no public creator posts were available.

# paths./v1/influencer/ins/fetchPosts.get.responses.403.description
The API key does not have permission for this operation.

# paths./v1/influencer/ins/fetchPosts.get.responses.429.description
Too many requests. Retry with exponential backoff.

# paths./v1/influencer/ins/fetchPosts.get.responses.429.headers.Retry-After.description
Seconds to wait before retrying, when provided.

# paths./v1/influencer/ins/fetchPosts.get.responses.500.description
Unexpected server error. Retry transient failures with exponential backoff.

# paths./v1/influencer/ins/fetchPosts.get.x-ui.summary
按 Instagram 用户名获取公开账号信息及近期帖子，用于达人分析与内容对标。

# paths./v1/influencer/ins/fetchPosts.get.x-ui.summaryEn
Fetch a public Instagram profile and recent posts for creator analysis and content benchmarking.

# paths./v1/influencer/ins/fetchPosts.get.x-ui.parameters[].descriptionEn
Instagram username without the leading @

# paths./v1/influencer/ins/fetchPosts.get.x-ui.parameters[].description
返回的近期帖子数量，默认 40

# paths./v1/influencer/ins/fetchPosts.get.x-ui.parameters[].descriptionEn
Number of recent posts to return; defaults to 40

# paths./v1/influencer/ins/fetchPosts.get.x-ui.notes[]
图片或图集帖子可能没有播放量，列表数据也可能缺少部分互动字段；缺失值不应直接解释为表现差。

# paths./v1/influencer/ins/fetchPosts.get.x-ui.notes[]
HTTP 200 且 code=0 才表示成功；code=-1 表示未获取到公开达人作品数据。

# paths./v1/influencer/ins/fetchPosts.get.x-ui.notesEn[]
Image and carousel posts may not have video views, and list data can omit some engagement fields. Do not interpret missing metrics as poor performance.

# paths./v1/influencer/ins/fetchPosts.get.x-ui.notesEn[]
Treat the request as successful only when HTTP is 200 and code is 0. code -1 means no public creator posts were available.

# paths./v1/influencer/ins/fetchPosts.get.x-ui.notesEn[]
To generate an AI creator report, turn this response into evidence and send it to /v1/relay/chat/completions.

# paths./v1/material/fetch.post.description
Fetches public video views and engagement metrics. Supported sources include TikTok, Instagram, Douyin, Xiaohongshu, WeChat Channels, and YouTube.

# paths./v1/material/fetch.post.responses.200.description
Public video data returned successfully.

# paths./v1/material/fetch.post.responses.403.description
The API key does not have permission for this operation.

# paths./v1/material/fetch.post.responses.404.description
The public work does not exist or has been deleted.

# paths./v1/material/fetch.post.responses.429.description
Too many requests. Retry with exponential backoff.

# paths./v1/material/fetch.post.responses.429.headers.Retry-After.description
Seconds to wait before retrying, when provided.

# paths./v1/material/fetch.post.responses.500.description
Unexpected server error. Retry transient failures with exponential backoff.

# paths./v1/material/fetch.post.x-ui.summary
根据公开作品链接同步 TikTok、Instagram、抖音、小红书、视频号和 YouTube 的播放与互动数据。

# paths./v1/material/fetch.post.x-ui.summaryEn
Fetch public video views and engagement metrics from TikTok, Instagram, Douyin, Xiaohongshu, WeChat Channels, and YouTube.

# paths./v1/material/analysisTask/stream.post.description
Analyzes a public video or an uploaded file and streams a natural-language replication prompt as server-sent events. Use `type: REPLICATION` for viral-video prompt replication. Send either a public `url`, or `businessId` with `businessType` after uploading a local file. Supported public sources include TikTok, Douyin, Xiaohongshu, WeChat Channels, Instagram, YouTube, and Bilibili. Each SSE `data:` line is a JSON object. Concatenate `result` from `status: "streaming"` events in arrival order. If a `status: "done"` event arrives, its `result` is the complete prompt and can replace the assembled chunks. The server may close the stream without a done event. HTTP errors return JSON and no SSE frames.

# paths./v1/material/analysisTask/stream.post.responses.200.description
Replication prompt streamed as server-sent events. Each data line is a MaterialAnalysisStreamEvent JSON object.

# paths./v1/material/analysisTask/stream.post.responses.200.content.text/event-stream.examples.streaming.value.result
**Video Script Title**
A clean product reveal with a slow camera push-in.

# paths./v1/material/analysisTask/stream.post.responses.200.content.text/event-stream.examples.done.value.result
**Video Script Title**
A clean product reveal with a slow camera push-in.

**Characters / Main Subjects**
A seller presenting a summer product against a bright studio backdrop.

**Scene / Environment**
Bright studio lighting, close-up product shots, and a final call to action.

**Script**
00:00-00:02 Hook the viewer with the product in hand.
00:02-00:08 Show the key selling points in short cuts.
00:08-00:10 End with a clear purchase CTA.

**Notes**
Keep the pacing tight and preserve the original hook-to-CTA structure.

# paths./v1/material/analysisTask/stream.post.responses.403.description
The API key does not have permission for this operation.

# paths./v1/material/analysisTask/stream.post.responses.429.description
Too many requests. Retry with exponential backoff.

# paths./v1/material/analysisTask/stream.post.responses.429.headers.Retry-After.description
Seconds to wait before retrying, when provided.

# paths./v1/material/analysisTask/stream.post.responses.500.description
Unexpected server error. Retry transient failures with exponential backoff.

# paths./v1/material/analysisTask/stream.post.x-ui.summary
根据公开视频链接或已上传文件，流式返回可用于二创的爆款视频提示词。将 streaming 事件中的 result 按到达顺序拼接；若收到 done 事件，以其 result 作为完整提示词。

# paths./v1/material/analysisTask/stream.post.x-ui.summaryEn
Stream a reusable replication prompt from a public video URL or an uploaded file. Concatenate result from streaming events in order; if a done event arrives, use its result as the complete prompt.

# paths./v1/material/analysisTask/stream.post.x-ui.parameters[].descriptionEn
Always send REPLICATION; ANALYSIS is reserved and not covered here

# paths./v1/material/analysisTask/stream.post.x-ui.parameters[].descriptionEn
Public video URL; send this or businessId. Supports TikTok, Douyin, Xiaohongshu, WeChat Channels, Instagram, YouTube, and Bilibili

# paths./v1/material/analysisTask/stream.post.x-ui.parameters[].description
已上传文件或素材 ID；与 url 二选一。本地文件请先走预签名上传，再传入 fileId 字符串

# paths./v1/material/analysisTask/stream.post.x-ui.parameters[].descriptionEn
Uploaded file or material ID; send this or url. Upload a local file first, then pass the fileId as a string

# paths./v1/material/analysisTask/stream.post.x-ui.parameters[].description
与 businessId 一起使用；本地上传文件传 FILE，素材库已有素材传 MATERIAL

# paths./v1/material/analysisTask/stream.post.x-ui.parameters[].descriptionEn
Required with businessId; use FILE for uploaded files and MATERIAL for library assets

# paths./v1/material/analysisTask/stream.post.x-ui.responseExample.result
**Video Script Title**
A clean product reveal with a slow camera push-in.

# paths./v1/material/analysisTask/stream.post.x-ui.notes[]
成功时响应 Content-Type 为 text/event-stream，不要按 JSON 的 code === 0 判断成功。

# paths./v1/material/analysisTask/stream.post.x-ui.notes[]
每条 SSE 行为 data:<json>；json 含 status、result、thinking 和任务 id。同一请求的 id 保持不变。

# paths./v1/material/analysisTask/stream.post.x-ui.notes[]
按到达顺序拼接 status=streaming 的 result。若出现 status=done，以其 result 作为完整提示词。

# paths./v1/material/analysisTask/stream.post.x-ui.notes[]
请求失败时直接返回 JSON 错误体，不会进入 SSE。请读取 HTTP 状态码和 message。

# paths./v1/material/analysisTask/stream.post.x-ui.notes[]
本地 MP4 请先调用 /v1/file/presign 与 /v1/file/confirm，再传 businessId 和 businessType=FILE。

# paths./v1/material/analysisTask/stream.post.x-ui.notes[]
完整提示词通常是 Markdown 结构，包含标题、主体、场景、分镜脚本和制作笔记，可继续用于 AI 视频生成。

# paths./v1/material/analysisTask/stream.post.x-ui.notesEn[]
A successful response uses Content-Type text/event-stream. Do not judge success by JSON code === 0.

# paths./v1/material/analysisTask/stream.post.x-ui.notesEn[]
Each SSE line is data:<json> with status, result, thinking, and a task id. The id stays constant for one request.

# paths./v1/material/analysisTask/stream.post.x-ui.notesEn[]
Concatenate result from status=streaming events in arrival order. If status=done arrives, use that result as the complete prompt.

# paths./v1/material/analysisTask/stream.post.x-ui.notesEn[]
Failures return a JSON error body instead of SSE. Read the HTTP status and message.

# paths./v1/material/analysisTask/stream.post.x-ui.notesEn[]
For a local MP4, call /v1/file/presign and /v1/file/confirm first, then send businessId with businessType=FILE.

# paths./v1/material/analysisTask/stream.post.x-ui.notesEn[]
The assembled prompt is usually Markdown with title, subjects, scene, timestamped script, and notes, and can feed AI video generation.

# paths./v1/relay/chat/completions.post.summary
Relay a chat completion to a supported model

# paths./v1/relay/chat/completions.post.description
Creates an OpenAI-compatible chat completion with a supported LINGTU relay model. Set `stream: true` to receive SSE chunks. Concatenate `choices[0].delta.content` until the terminal `data: [DONE]` event. Set `stream: false` to receive one JSON completion and read `choices[0].message.content`. Messages may contain plain text or supported image_url content parts.

# paths./v1/relay/chat/completions.post.responses.200.description
A JSON completion when stream is false, or OpenAI-compatible server-sent events when stream is true.

# paths./v1/relay/chat/completions.post.responses.403.description
The API key does not have permission for this operation.

# paths./v1/relay/chat/completions.post.responses.429.description
Too many requests. Retry with exponential backoff.

# paths./v1/relay/chat/completions.post.responses.429.headers.Retry-After.description
Seconds to wait before retrying, when provided.

# paths./v1/relay/chat/completions.post.responses.500.description
Unexpected server error. Retry transient failures with exponential backoff.

# paths./v1/relay/chat/completions.post.x-ui.summary
通过统一的 OpenAI 兼容接口调用灵途支持的文本与视觉模型，支持普通 JSON 和 SSE 流式响应。

# paths./v1/relay/chat/completions.post.x-ui.summaryEn
Call supported LINGTU text and vision models through one OpenAI-compatible endpoint with JSON or SSE streaming responses.

# paths./v1/relay/chat/completions.post.x-ui.parameters[].description
要调用的模型标识，必须是当前账号可用的受支持模型

# paths./v1/relay/chat/completions.post.x-ui.parameters[].descriptionEn
Supported model identifier available to the current account

# paths./v1/relay/chat/completions.post.x-ui.parameters[].description
OpenAI 兼容的对话消息，支持文本及受支持的 image_url 内容

# paths./v1/relay/chat/completions.post.x-ui.parameters[].descriptionEn
OpenAI-compatible messages with text and supported image_url content

# paths./v1/relay/chat/completions.post.x-ui.parameters[].descriptionEn
When true, returns incremental SSE content; defaults to false

# paths./v1/relay/chat/completions.post.x-ui.parameters[].description
在模型支持时启用或关闭思考模式

# paths./v1/relay/chat/completions.post.x-ui.parameters[].descriptionEn
Enable or disable thinking when supported by the selected model

# paths./v1/relay/chat/completions.post.x-ui.notes[]
API Key 只能保存在服务端，不要把 x-api-key 写入浏览器代码、日志或公开文件。

# paths./v1/relay/chat/completions.post.x-ui.notes[]
stream=true 时逐条解析 data: 行，拼接 choices[0].delta.content；收到 data: [DONE] 后结束。

# paths./v1/relay/chat/completions.post.x-ui.notes[]
算力消耗取决于所选模型、输入内容、输出长度以及是否包含图片等多模态内容。

# paths./v1/relay/chat/completions.post.x-ui.notes[]
image_url 必须是模型服务可访问的 URL，并根据业务需要选择合适的 detail。

# paths./v1/relay/chat/completions.post.x-ui.notesEn[]
Keep API keys on the server. Never place x-api-key in browser code, logs, or public files.

# paths./v1/relay/chat/completions.post.x-ui.notesEn[]
With stream=true, parse each data: line and concatenate choices[0].delta.content until data: [DONE].

# paths./v1/relay/chat/completions.post.x-ui.notesEn[]
Compute usage depends on the selected model, input content, output length, and multimodal inputs such as images.

# paths./v1/relay/chat/completions.post.x-ui.notesEn[]
image_url must be reachable by the model service; choose an appropriate detail level for the task.

# components.securitySchemes.ApiKeyAuth.description
LINGTU AI API key. Keep it on the server and never expose it in client-side code or logs.

# components.schemas.ErrorResponse.properties.code.description
Non-zero business or HTTP-aligned error code.

# components.schemas.CreatorAccount.properties.id.description
Account table ID used by product query endpoints.

# components.schemas.CreatorAccount.properties.creatorId.description
Creator business ID used when creating publishing tasks.

# components.schemas.AddShowcaseProductsResponse.properties.code.description
Business status code. Zero means the request was processed.

# components.schemas.AddShowcaseProductsResponse.properties.data.properties.errors.description
Per-product failures. May be empty or omitted when every product succeeds.

# components.schemas.PresignRequest.properties.hash.description
Compatibility hash: lowercase hex of the raw file bytes, UTF-8 encoded, then SHA-256.

# components.schemas.TikTokShopVideoOptions.properties.preCheck.description
Whether to submit the video for pre-check before publishing.

# components.schemas.TikTokShopVideoOptions.properties.isAiGenerated.description
Whether TikTok should label the commerce video as AI-generated.

# components.schemas.TikTokShopVideoOptions.properties.coverUri.description
Cover URI returned by the cover upload endpoint. Pass coverFileId at the request root when using it.

# components.schemas.TikTokShopVideoOptions.properties.coverTimestampMs.description
Video timestamp in milliseconds to use as the cover frame. Omit when coverUri is present.

# components.schemas.PostRequestBase.properties.coverFileId.description
Custom video cover file ID. Pass together with tiktokShop.coverUri and omit for photo posts.

# components.schemas.PostRequestBase.properties.scheduledTz.description
IANA timezone, for example America/New_York.

# components.schemas.AiVideoGenerationParams.properties.seconds.description
Allowed durations depend on the selected model.

# components.schemas.TikTokCreatorPost.properties.duration.description
Video duration as returned by the upstream source, commonly milliseconds.

# components.schemas.MaterialFetchResponse.properties.data.description
Normalized and platform-specific public content fields.

# components.schemas.MaterialAnalysisStreamUrlRequest.properties.url.description
Public TikTok, Douyin, Xiaohongshu, WeChat Channels, Instagram, YouTube, or Bilibili video URL.

# components.schemas.MaterialAnalysisStreamFileRequest.properties.businessId.description
Uploaded file ID or material ID. Pass the fileId from the upload flow as a string.

# components.schemas.MaterialAnalysisStreamFileRequest.properties.businessType.description
FILE for a newly uploaded file; MATERIAL for an existing library asset.

# components.schemas.MaterialAnalysisStreamEvent.properties.status.description
streaming is an incremental chunk; done is the complete prompt when the server sends a terminal event.

# components.schemas.MaterialAnalysisStreamEvent.properties.result.description
Incremental prompt text for streaming events, or the complete prompt for a done event.

# components.schemas.MaterialAnalysisStreamEvent.properties.id.description
Analysis task ID. Constant across chunks for a single request.