Skip to main content
Directing Open API Reference

HappyOyster-Directing-Query Travel Artifacts API Reference

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).
  • 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
  • US (Virginia)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/travels/artifactsReplace {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
  • Composition still processing
{
    "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
            }
        }
    }
}
code integerReturn code. 0 means success; non-zero is an error code.
message stringError message. null on success.
data objectResponse data. null on failure.

Properties

encryptedTravelId stringEncrypted Travel ID.composeStatus stringThe 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 objectThe 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 stringVideo URL; null when status=processing.video.*.status stringPer-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 stringvideo.original.resolution is "720p" when the original matches 720p; otherwise it is null.video.*.durationSec integerThe 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

API Usage
Text Generation
Image Generation
  • FAQ
Video Generation
World models
Audio
  • Audio generation
Real-time Multimodal
Realtime API
Text Embedding
Decision Model
More Models
Toolkit/Framework
TokenPlan
Model Production
File Management
Billing
Model Management
More