[API Change Notice] Asynchronous Task Retrieval — Response Envelope Removal

[tensornull]

[API Change Notice] Asynchronous Task Retrieval — Response Envelope Removal

Field	Value
Notice type	Breaking change
Component	Asynchronous task retrieve / poll endpoints
Effective date	2026-04-28 00:00 UTC (Tuesday)
Rollout	Global, all CometAPI regions
Action required	Yes — client-side parser update
Rollback window	None after the effective date

---

1. Summary

To improve consistency with upstream providers and to align the retrieve
path with the already-unwrapped create path, CometAPI will remove the
{code, message, data: {...}} wrapper envelope from the response body of
all asynchronous task retrieve / poll endpoints.

Starting from the effective date, retrieve endpoints will return the
upstream provider's native JSON body at the top level, identical in
shape to what the respective model provider's official API returns.

2. Scope

2.1 Affected endpoints

The change applies to the GET / poll side of the following asynchronous
suppliers:

Supplier	Endpoint pattern
Kling	GET /kling/v1/videos/{action}/{task_id} and related paths
Replicate	GET /replicate/v1/predictions/{id}
Runway	POST /runway/feed and related retrieve paths
Bria	GET /bria/{request_id}
Flux	GET /flux/v1/get_result
xAI (Grok)	GET /grok/v1/videos/{request_id}

Any other asynchronous supplier whose current retrieve response is
wrapped in the {code, message, data: {...}} envelope is also included
in this change.

2.2 Not affected

• create (POST) endpoints — the request and response formats remain unchanged.
• Synchronous endpoints — chat/completions, responses, embeddings, and other sync APIs are not affected.
• Authentication, URL paths, HTTP methods, and rate-limiting behavior — unchanged.

3. Technical details

3.1 Current behavior (before 2026-04-28)

Retrieve responses are wrapped in a CometAPI-specific envelope that
embeds the upstream body at .data.data:

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "<id>",
    "action": "<normalized_action>",
    "status": "<normalized_status>",
    "fail_reason": "",
    "submit_time": 0,
    "start_time": 0,
    "finish_time": 0,
    "progress": "<percent>",
    "data": { /* upstream provider's native body */ }
  }
}

3.2 New behavior (on and after 2026-04-28)

The envelope and all CometAPI-normalized fields are removed. The response
body is the upstream provider's native JSON, served directly:

{ /* upstream provider's native body */ }

3.3 Reference example — Kling text-to-video retrieve

Before:

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "2046194428712378368",
    "action": "TEXT2VIDEO",
    "status": "NOT_START",
    "fail_reason": "",
    "submit_time": 1776685744,
    "start_time": 0,
    "finish_time": 0,
    "progress": "0%",
    "data": {
      "task_id": "2046194428712378368",
      "task_info": {},
      "created_at": 1776685742916,
      "updated_at": 1776685742916,
      "task_status": "submitted"
    }
  }
}

After:

{
  "task_id": "2046194428712378368",
  "task_info": {},
  "created_at": 1776685742916,
  "updated_at": 1776685742916,
  "task_status": "submitted"
}

3.4 Additional example — xAI (Grok) video retrieve

Before:

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "<request_id>",
    "action": "VIDEO_GENERATION",
    "status": "NOT_START",
    "fail_reason": "",
    "submit_time": 0,
    "start_time": 0,
    "finish_time": 0,
    "progress": "0%",
    "data": {
      "request_id": "<request_id>"
    }
  }
}

After:

{
  "request_id": "<request_id>"
}

3.5 Field-level impact

Field (current path)	Status after 2026-04-28	Replacement
code, message (root)	Removed	HTTP status code + upstream error body
data.action	Removed	Derive from the endpoint you called
data.status	Removed	Upstream provider's native state field (e.g., task_status, status)
data.progress	Removed	Upstream provider's native progress field, if any
data.fail_reason	Removed	Upstream provider's native error field
data.submit_time / start_time / finish_time	Removed	Upstream timestamps (created_at, updated_at, etc.)
data.data.* (upstream body)	Promoted to root	Parse the response root directly

4. Migration guide

1. Update your parser to treat the retrieve response root as the
   upstream provider's native body. Remove any access to
   response.data.data.* and read fields directly from response.*.
2. Switch task state/progress handling from the CometAPI-normalized
   fields (status, progress, fail_reason) to the upstream
   provider's own state fields, which vary per supplier.
3. Regenerate data models / typed clients (Pydantic models,
   TypeScript interfaces, Go structs, Java DTOs, etc.) against the new
   shape.
4. Update error handling to align with the upstream provider's
   native error semantics — HTTP status codes and the provider's own
   error body — rather than the CometAPI {code, message} envelope.
5. Test in staging against the current production endpoints. Since
   the wrapper removal is purely a response-shape change, you can
   validate the new parser against the upstream body nested at
   response.data.data today.

For the exact response schema, field semantics, and error codes of
each supplier, please refer directly to the official documentation of
the respective model provider. CometAPI preserves the provider's
native contract; any field present in the provider's documented
response will be present in the new CometAPI response, at the same
JSON path.

5. Recommended timeline

Date	Action
2026-04-21 – 2026-04-27	Update, test, and stage the new parser.
2026-04-28 00:00 UTC	New format goes live in production.
2026-04-28 onward	Monitor error rates; contact support for any regressions.

6. Support

If you encounter any issue during migration, please contact the CometAPI
support team through your usual channel. Please include:

• The affected endpoint and a sample task_id / request_id.
• A request/response sample (with credentials redacted).
• The timestamp of the call (UTC preferred).

We apologize for the disruption this change may cause and appreciate
your cooperation in making the CometAPI platform more consistent and
standards-aligned.

— The CometAPI Engineering Team