Skip to content

Text ​

Create a text caption task ​

POST/texts/captions

Generate a short caption for an input text in the requested language. The request can run synchronously or return a task for polling.

请求体

Content-Type: application/jsonRequired: true
Request Body Schema
application/json
└input_text
required
string(Input Text)[1..∞] chars

Source text to analyze and caption.

└language
required
string(Language)[1..64] chars

Target language for the generated caption, for example English, Chinese, or Japanese.

└options
TaskRequestOptions | null

Optional task execution controls for the task

└block
boolean | null

When true, wait for task completion and return the terminal response immediately. When false, return a task reference for polling.

响应

通用错误码说明请查看:错误处理。

Response Schema
200application/json
└task_uuid
required
string(Task Uuid)

Unique identifier for the task

└task_type
required
string(Task Type)

Logical task category used by the backend pipeline.

└model
required
string(Model)

Model or worker name assigned to the task.

└status
required
string(TaskStatus)
Enum: QUEUED PROCESSING COMPLETED FAILED
└created_at
required
integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at
integer | null

Unix timestamp, in seconds, when the task finished successfully. May be absent when the terminal snapshot is built before the completion timestamp is finalized.

└result
required
string(Result)

Short caption generated for the input text in the requested language.

└metadata
ImageCaptionMetadata | null

Additional caption metadata including description and keywords.

└description
string(Description)

Brief description of the image content.

Default: ``

└keywords
array(Keywords)

Relevant keywords describing the image.

└keywords[]
string
也可能返回 201,表示任务已接受并在后台异步执行。使用响应体中的 task_uuid 轮询对应的 GET 端点获取结果。了解同步 vs 异步 →
curl -X POST 'https://api.v2fun.ai/api/v1/texts/captions' \
  -H "Authorization: Bearer $V2FUN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
      "input_text": "<input_text>",
      "language": "<language>"
    }'
Response 200 OK
{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "result": "<result>"
}

Get a text caption task ​

GET/texts/captions/{task_uuid}

Retrieve the current status or final result of a text caption task.

参数

名称位置必填类型说明
task_uuidpath是stringTask UUID returned when the text caption job was created.

响应

通用错误码说明请查看:错误处理。

Response Schema
200application/json
└task_uuid
required
string(Task Uuid)

Unique identifier for the task

└task_type
required
string(Task Type)

Logical task category used by the backend pipeline.

└model
required
string(Model)

Model or worker name assigned to the task.

└status
required
string(TaskStatus)
Enum: QUEUED PROCESSING COMPLETED FAILED
└created_at
required
integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at
integer | null

Unix timestamp, in seconds, when the task finished successfully. May be absent when the terminal snapshot is built before the completion timestamp is finalized.

└result
required
string(Result)

Short caption generated for the input text in the requested language.

└metadata
ImageCaptionMetadata | null

Additional caption metadata including description and keywords.

└description
string(Description)

Brief description of the image content.

Default: ``

└keywords
array(Keywords)

Relevant keywords describing the image.

└keywords[]
string
curl -X GET 'https://api.v2fun.ai/api/v1/texts/captions/<task_uuid>' \
  -H "Authorization: Bearer $V2FUN_API_KEY"
Response 200 OK
{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "result": "<result>"
}

Create a text rank task ​

POST/texts/rankings

Rank candidate texts by semantic relevance to a query and return the top-N matches. The request can run synchronously or return a task for polling.

请求体

Content-Type: application/jsonRequired: true
Request Body Schema
application/json
└query
required
string(Query)[1..∞] chars

Query text whose semantic relevance is used to rank the candidates.

└candidates
required
array(Candidates)[1..∞] items

Candidate texts to be ranked by relevance to the query.

└candidates[]
string
└top_n
integer(Top N)[1..∞]

Number of top-ranked candidates to return. Must be <= len(candidates).

Default: `1`

└options
TaskRequestOptions | null

Optional task execution controls for the task

└block
boolean | null

When true, wait for task completion and return the terminal response immediately. When false, return a task reference for polling.

响应

通用错误码说明请查看:错误处理。

Response Schema
200application/json
└task_uuid
required
string(Task Uuid)

Unique identifier for the task

└task_type
required
string(Task Type)

Logical task category used by the backend pipeline.

└model
required
string(Model)

Model or worker name assigned to the task.

└status
required
string(TaskStatus)
Enum: QUEUED PROCESSING COMPLETED FAILED
└created_at
required
integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at
integer | null

Unix timestamp, in seconds, when the task finished successfully. May be absent when the terminal snapshot is built before the completion timestamp is finalized.

└result
required
array(Result)

Ordered list of candidate texts with the highest semantic relevance to the query (highest first). Length equals min(top_n, len(candidates)).

└result[]
string
└metadata
TextRankResultMetadata[] | null

Per-result metadata: the original candidate index and the relevance score.

└metadata[]
object(TextRankResultMetadata)
└index
required
integer(Index)[0..∞]

Original index of the candidate in the request candidates list (0-based).

└relevance_score
number | null

Normalized relevance score returned by the rerank model, when available.

也可能返回 201,表示任务已接受并在后台异步执行。使用响应体中的 task_uuid 轮询对应的 GET 端点获取结果。了解同步 vs 异步 →
curl -X POST 'https://api.v2fun.ai/api/v1/texts/rankings' \
  -H "Authorization: Bearer $V2FUN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
      "query": "<query>",
      "candidates": []
    }'
Response 200 OK
{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "result": []
}

Get a text rank task ​

GET/texts/rankings/{task_uuid}

Retrieve the current status or final result of a text rank task.

参数

名称位置必填类型说明
task_uuidpath是stringTask UUID returned when the text rank job was created.

响应

通用错误码说明请查看:错误处理。

Response Schema
200application/json
└task_uuid
required
string(Task Uuid)

Unique identifier for the task

└task_type
required
string(Task Type)

Logical task category used by the backend pipeline.

└model
required
string(Model)

Model or worker name assigned to the task.

└status
required
string(TaskStatus)
Enum: QUEUED PROCESSING COMPLETED FAILED
└created_at
required
integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at
integer | null

Unix timestamp, in seconds, when the task finished successfully. May be absent when the terminal snapshot is built before the completion timestamp is finalized.

└result
required
array(Result)

Ordered list of candidate texts with the highest semantic relevance to the query (highest first). Length equals min(top_n, len(candidates)).

└result[]
string
└metadata
TextRankResultMetadata[] | null

Per-result metadata: the original candidate index and the relevance score.

└metadata[]
object(TextRankResultMetadata)
└index
required
integer(Index)[0..∞]

Original index of the candidate in the request candidates list (0-based).

└relevance_score
number | null

Normalized relevance score returned by the rerank model, when available.

curl -X GET 'https://api.v2fun.ai/api/v1/texts/rankings/<task_uuid>' \
  -H "Authorization: Bearer $V2FUN_API_KEY"
Response 200 OK
{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "result": []
}