Skip to main content

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
Video Generation
World models
3D Model Generation
Audio
  • Audio generation
Real-time Multimodal
Realtime API
Text Embedding
Translation models
Decision Model
More Models
Toolkit/Framework
TokenPlan
Model Production
File Management
Billing
Model Management
More