HappyOyster-Acting-Query Travel Artifacts API Reference - Alibaba Cloud Model Studio

Query the recorded original and the three composited variants of a completed Acting Travel. For external delivery, withInstructionAndWatermark is recommended.

Scope

Query the recorded original and the three composited variants of a completed Acting Travel. withInstruction is the overlay variant of the user's process instructions; for external delivery, withInstructionAndWatermark is recommended. Before calling, confirm the following:

Authentication: Only the primary API Key is supported; temporary API Keys cannot be used (error code 403003).
- Get the primary API Key: Get and configure an API Key.
Prerequisites: The Travel status is completed. An available original URL is the precondition for returning an artifacts response. Confirm via Query Travel Status.
Caller: Called by your server.

HTTP request

Singapore

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/travels/artifacts

Replace {WorkspaceId} with your actual Workspace ID.

US (Virginia)

GET https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/travels/artifacts

Replace {WorkspaceId} with your actual Workspace ID.

Request parameters	Query Travel artifacts `curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/travels/artifacts?encryptedTravelId={encryptedTravelId}' \ -H "Authorization: Bearer $DASHSCOPE_API_KEY"`
Authorization `string` (Required) API Key authentication. Only the primary API Key is supported; it starts with `sk-`, e.g. `sk-xxx`. It is typically configured as the environment variable `$DASHSCOPE_API_KEY`. A temporary API Key (starting with `st-`) returns `403003`.
Query parameters
encryptedTravelId `string` (Required) An Acting encrypted Travel ID with status `completed`. Returned by Enter Travel.

Response parameters

All four artifacts ready

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "composeStatus": "ready",
        "video": {
            "original": {
                "url": "https://cdn.happyoyster.com/exports/trvl_a1b2c3d4e5f6_raw.mp4?v=2",
                "status": "ready",
                "resolution": "720p",
                "durationSec": 180
            },
            "withWatermark": {
                "url": "https://cdn.happyoyster.com/exports/trvl_a1b2c3d4e5f6_wm.mp4?v=2",
                "status": "ready",
                "resolution": null,
                "durationSec": 180
            },
            "withInstruction": {
                "url": "https://cdn.happyoyster.com/exports/trvl_a1b2c3d4e5f6_overlay.mp4?v=2",
                "status": "ready",
                "resolution": null,
                "durationSec": 180
            },
            "withInstructionAndWatermark": {
                "url": "https://cdn.happyoyster.com/exports/trvl_a1b2c3d4e5f6_all.mp4?v=2",
                "status": "ready",
                "resolution": null,
                "durationSec": 180
            }
        }
    }
}

Composition still processing

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "composeStatus": "processing",
        "video": {
            "original": {
                "url": "https://cdn.happyoyster.com/exports/trvl_a1b2c3d4e5f6_raw.mp4?v=2",
                "status": "ready",
                "resolution": "720p",
                "durationSec": 180
            },
            "withWatermark": {
                "url": null,
                "status": "processing",
                "resolution": null,
                "durationSec": null
            },
            "withInstruction": {
                "url": null,
                "status": "processing",
                "resolution": null,
                "durationSec": null
            },
            "withInstructionAndWatermark": {
                "url": null,
                "status": "processing",
                "resolution": null,
                "durationSec": null
            }
        }
    }
}

code integer

Return code. 0 means success; non-zero is an error code.

message string

Error message. null on success.

data object

Response data. null on failure.

Properties

encryptedTravelId string

Encrypted Travel ID.

composeStatus string

The aggregated status of the three composited variants:

ready: withWatermark, withInstruction, and withInstructionAndWatermark are all ready
partial: at least one composited variant is ready, but not all
processing: none of the three composited variants is ready

It aggregates only the three composited variants and does not include original.

video object

The four fixed variants of the main video. Each item contains url, status, resolution, and durationSec.

original: the recorded original; a 720p representation is returned preferentially when available
withWatermark: watermark-only composited variant
withInstruction: composited variant with the user's process-instruction overlay
withInstructionAndWatermark: user's process-instruction overlay + watermark composited variant, recommended for external delivery

video.*.url string

Download URL; null when processing or unavailable.

video.*.status string

Per-item status:

ready: ready, url is accessible
processing: still compositing, url=null
unavailable: composition failed or the URL is temporarily unavailable, url=null

video.*.resolution string

"720p" when original matches 720p; otherwise it may be null.

video.*.durationSec integer

The uniformly parsed video duration in seconds; when parseable, all ready variants carry this value. It may be null when processing / unavailable or when the duration cannot yet be parsed.

Prerequisite states and call notes

The client can poll at a controlled interval while composeStatus != ready.
video.withInstruction is the process-instruction overlay variant, not the instruction-free original.
For external delivery, read video.withInstructionAndWatermark; if your business only needs the original, keep reading video.original.url.
The four video variants share the same duration-parsing result, so within one response the ready variants with a parseable duration return a consistent durationSec.
A Travel ended by TRAVEL_NO_STREAM_AUTO_END is failed and generates no queryable artifacts.
Do not always render 404000 as "not yet complete": first read status and errorCode via Query Travel Status or Query Travel List; for a failed Travel, show the failure reason.

404000 scenarios

Scenario	Endpoint behavior
The Travel is still in progress (`init` / `pending` / `running` / `paused`)	Returns business code `404000`, with `message` = `Video is still being generated, please try again once the process is complete`
The Travel is `failed`	Returns business code `404000`, with `message` = `Experience failed and no video was produced (errorCode=<errorCode>): <errorMessage>`; failure is terminal and no video will be produced
The Travel does not exist, does not belong to you, or is not Acting	Returns business code `404000`
The original URL is unavailable	Returns business code `404000`; the original is the hard gate for the whole endpoint
The original is ready and composition is still processing	HTTP 200; the corresponding composited item has `status=processing`, `url=null`
Composition failed or the URL is temporarily unavailable	HTTP 200; the corresponding composited item has `status=unavailable`, `url=null`

Error codes

If the model call fails and returns an error, see HappyOyster Error Codes to resolve it.

Next steps

Query Travel List: view other historical Travels.
End Travel: end a new Travel before querying its artifacts.