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

Query the recorded original and the three composited variants of a completed Directing Travel. An available original is the precondition for returning an artifacts response; for external delivery, withInstructionAndWatermark is recommended.

Scope

Query the recorded original and the three composited variants of a completed Directing Travel. An available original is the precondition for returning an artifacts response; the composited variants may still be processing. 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 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-directing/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-directing/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-directing/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) A Directing 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 main-line video artifacts, with a fixed field structure. Each item contains url, status, resolution, and durationSec.

original: the recorded original; a 720p representation is preferred
withWatermark: watermark-only composited variant
withInstruction: composited variant with user-instruction subtitles only
withInstructionAndWatermark: composited variant with user-instruction subtitles and watermark, recommended for external delivery

video.*.url string

Video URL; null when status=processing.

video.*.status string

Per-item status:

ready: the video is ready and the URL is accessible
processing: still processing; url is null
unavailable: composition failed or the URL is temporarily unavailable

video.*.resolution string

video.original.resolution is "720p" when the original matches 720p; otherwise it is 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

When the Travel is not completed, does not exist, does not belong to you or is not Directing, or the original is not available, 404000 is returned; an available original is the precondition for returning an artifacts response.
When you need all composited variants, you can keep polling while composeStatus != ready.
video.withInstructionAndWatermark is the recommended variant for external delivery.
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.

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.