Skip to main content

​
Seedance 2.0 Face Authentication

Some Seedance 2.0 use cases — for example driving a video with a specific person’s face — require the reference asset to be registered and authenticated with the upstream provider before it can be used. Sunra exposes a small Ark Assets API that handles this for you: you submit the URL of an image (or video / audio), Sunra registers it upstream, and once it becomes active you can reference it in your Seedance 2.0 generation. These endpoints do not run an inference pipeline — there is no prediction record, no queue, and no per-call inference billing. They are a thin management layer over the upstream asset registry.

​
Authentication

Authentication is the same as the rest of the Sunra API — send your API key in the Authorization header: 
Authorization: Bearer $SUNRA_API_KEY
All Ark Assets endpoints are scoped to your organization; you can only see and manage assets your organization created.

​
Workflow

  1. Create the asset from a source URL → returns an ark_asset_id with status: "processing".
  2. Poll the asset with Get asset until status becomes active.
  3. Use asset://<ark_asset_id> as a reference in a Seedance 2.0 relay request (see Using the asset below).
Statuses: processing (registering upstream), active (ready to use), failed (registration failed).

​
Create an asset

POST https://api.sunra.ai/v1/ark/assets
FieldTypeRequiredDescription
source_urlstringyesPublicly accessible URL of the asset (e.g. a face image). Must be reachable by the server.
namestringnoFriendly name. Defaults to the filename inferred from source_url.
asset_typeimage | video | audionoAsset type. Inferred from the URL extension when omitted (defaults to image).
Response — the created asset: 
{
  "id": "665f1c...",
  "ark_asset_id": "cgt-20260609-abc123",
  "name": "face.jpg",
  "asset_type": "image",
  "source_url": "https://example.com/face.jpg",
  "status": "processing",
  "created_at": "2026-06-09T15:00:00.000Z"
}

​
Get an asset

Fetches a single asset and refreshes its status from upstream. When the asset is ready, the response includes ark_url. 
GET https://api.sunra.ai/v1/ark/assets/{ark_asset_id}

{
  "id": "665f1c...",
  "ark_asset_id": "cgt-20260609-abc123",
  "name": "face.jpg",
  "asset_type": "image",
  "source_url": "https://example.com/face.jpg",
  "status": "active",
  "ark_url": "https://.../authenticated-asset",
  "created_at": "2026-06-09T15:00:00.000Z"
}

​
List assets

POST https://api.sunra.ai/v1/ark/assets/list
FieldTypeDefaultDescription
statusstring—Filter by status (processing | active | failed).
pageinteger1Page number.
page_sizeinteger20Items per page.
Response: 
{
  "items": [ { "ark_asset_id": "cgt-...", "status": "active", "asset_type": "image" } ],
  "total": 1,
  "page": 1,
  "page_size": 20
}

​
Delete an asset

Soft-deletes the asset from your organization’s list (the upstream registration is unaffected). 
DELETE https://api.sunra.ai/v1/ark/assets/{ark_asset_id}

{ "deleted": true }

​
Examples

# 1. Create
curl -X POST "https://api.sunra.ai/v1/ark/assets" \
  -H "Authorization: Bearer $SUNRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source_url":"https://example.com/face.jpg","asset_type":"image"}'

# 2. Poll until active
curl "https://api.sunra.ai/v1/ark/assets/cgt-20260609-abc123" \
  -H "Authorization: Bearer $SUNRA_API_KEY"

​
Using the asset in Seedance 2.0

Once the asset is active, reference it as asset://<ark_asset_id> inside reference_images (or reference_videos / reference_audios) of a Seedance 2.0 relay reference-to-video request, and mention it from the prompt with @Image1 (first image = @Image1, second = @Image2, …).
Use the authenticated relay endpoint. Face-authenticated (Ark) assets are only recognized on the relay models — bytedance/seedance-2.0-relay and bytedance/seedance-2.0-fast-relay. Pass the asset as asset://<ark_asset_id> (not a URL). The non-relay bytedance/seedance-2.0(-fast) models go straight to Volcengine and will reject asset:// with InvalidParameter. 
POST https://api.sunra.ai/v1/queue/bytedance/seedance-2.0-fast-relay/reference-to-video
FieldTypeDescription
promptstringPrompt; reference the asset with @Image1.
reference_imagesstring[]0–9 references. Put asset://<ark_asset_id> here.
resolution480p | 720p | 1080pOutput resolution (default 720p).
ratiostringAspect ratio; adaptive auto-selects.
durationintegerSeconds, 4–15 (or -1 for auto).
generate_audiobooleanGenerate synchronized audio (default true).
(Also available without the -fast suffix: bytedance/seedance-2.0-relay/reference-to-video.) 
curl -X POST "https://api.sunra.ai/v1/queue/bytedance/seedance-2.0-fast-relay/reference-to-video" \
  -H "Authorization: Bearer $SUNRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "the person in @Image1 is talking to the camera",
    "reference_images": ["asset://<ARK_ASSET_ID>"],
    "resolution": "720p",
    "ratio": "adaptive",
    "duration": 5,
    "generate_audio": true
  }'
Then poll the returned status_url until the prediction finishes (see Queue). If the upstream model’s content moderation rejects the input, the prediction completes with success: false and an unsafe_content error — revise the prompt or reference image and retry. (Real faces combined with minor-implying prompts are a common trigger.)