Skip to main content
Acting Open API Reference (Invitational Preview)

HappyOyster-Acting-Query Travel Artifacts API Reference

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).
  • 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
  • US (Virginia)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/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-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
  • 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 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 stringDownload URL; null when processing or unavailable.video.*.status stringPer-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 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

  • 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
ScenarioEndpoint 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 failedReturns 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 ActingReturns business code 404000
The original URL is unavailableReturns business code 404000; the original is the hard gate for the whole endpoint
The original is ready and composition is still processingHTTP 200; the corresponding composited item has status=processing, url=null
Composition failed or the URL is temporarily unavailableHTTP 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

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