diff --git a/.vitepress/theme/OfficialNativeApiSidebar.vue b/.vitepress/theme/OfficialNativeApiSidebar.vue index ac477c4e..9c139d88 100644 --- a/.vitepress/theme/OfficialNativeApiSidebar.vue +++ b/.vitepress/theme/OfficialNativeApiSidebar.vue @@ -18,6 +18,10 @@ const models = [ text: 'Seedance 2.0 Official', link: '/model-api-reference/official-native-api/bytedance/seedance-2.0-official', }, + { + text: 'Media Assets for Seedance', + link: '/model-api-reference/official-native-api/bytedance/media-assets', + }, ] const openaiModels = [ diff --git a/api-reference/models/assets.md b/api-reference/models/assets.md index bab0856d..df24d245 100644 --- a/api-reference/models/assets.md +++ b/api-reference/models/assets.md @@ -5,7 +5,11 @@ description: Register reusable media Assets and retrieve their current metadata # Media Assets API -Register media file URLs into the platform asset library and get an `asset_url` for use in video generation requests. +Use the official-compatible Asset protocol exposed at `/v1/assets` to register media URLs and get an `asset_url` for +native video generation requests. + +For an end-to-end example that registers media and uses the returned `asset://` reference with Seedance, see +[Media Assets for Seedance](/model-api-reference/official-native-api/bytedance/media-assets). ## Overview diff --git a/model-api-reference/official-native-api/bytedance/media-assets.md b/model-api-reference/official-native-api/bytedance/media-assets.md new file mode 100644 index 00000000..ffc6cdb4 --- /dev/null +++ b/model-api-reference/official-native-api/bytedance/media-assets.md @@ -0,0 +1,160 @@ +--- +title: Media Assets for Seedance +description: Register reusable media through the official-compatible Asset protocol, then use asset:// references with Seedance 2.0 and 2.5. +--- + +# Media Assets for Seedance + +SandBase exposes the official-compatible Asset protocol at `/v1/assets`. The Asset request and the returned `asset://` +reference follow the official protocol, and the reference is passed through unchanged in the native ByteDance Contents +Generations request. Both +[Seedance 2.5 Official](./seedance-2.5-official) and [Seedance 2.0 Official](./seedance-2.0-official) accept that reference +where they normally accept a public HTTP(S) URL. + +The complete workflow is: + +1. Register a reachable media URL with `POST /v1/assets`. +2. Query `GET /v1/assets/{external_id}` until the provider reports that the Asset is usable. +3. Put the returned `asset_url` in a Seedance `content` item and submit the generation task. + +## Official-compatible Asset operations + +| Method | Path | Purpose | +| --- | --- | --- | +| `POST` | `/v1/assets` | Register a reachable media URL and receive an official-compatible `asset://` reference | +| `GET` | `/v1/assets/{external_id}` | Read the provider status and obtain the current preview/download URL | + +The public API currently exposes registration and lookup. Asset groups, listing, renaming, updating, and deletion are +not public operations. Assets belong to the organization associated with the API key. + +## Step 1: register the Asset + +Send the reachable URL to `POST /v1/assets`. `asset_type` is case-sensitive and must be `Image`, `Video`, or `Audio`: + +```bash +curl -X POST https://api.sandbase.ai/v1/assets \ + -H "Authorization: Bearer $SANDBASE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "url": "https://example.com/product-reference.png", + "asset_type": "Image", + "name": "Product reference" + }' +``` + +Save `asset_url` from the response: + +```json +{ + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "asset_url": "asset://asset-20260710150403-hx4hf", + "asset_type": "Image", + "name": "Product reference", + "created_at": "2026-07-10T15:04:03Z" +} +``` + +The value after `asset://` is the `external_id` used by the official-compatible lookup operation. + +## Step 2: check readiness + +Query the Asset with the `external_id`, without the `asset://` prefix: + +```bash +curl https://api.sandbase.ai/v1/assets/asset-20260710150403-hx4hf \ + -H "Authorization: Bearer $SANDBASE_API_KEY" +``` + +```json +{ + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "external_id": "asset-20260710150403-hx4hf", + "asset_url": "asset://asset-20260710150403-hx4hf", + "status": "Active", + "asset_type": "Image", + "name": "Product reference", + "download_url": "https://media.example.com/current-signed-url", + "created_at": "2026-07-10T15:04:03Z" +} +``` + +Treat `status` as an open provider value rather than an exhaustive enum. Wait until the provider reports a usable +state before submitting the generation task; a common ready value is `Active`. `download_url` is provider-managed and +can be empty while processing. Query the Asset again when you need a current preview URL. Keep using the persistent +`asset_url` in Seedance requests rather than copying `download_url`. + +## Step 3: generate with the Asset + +Place `asset_url` in the URL field that matches the media type. This example uses the registered image as a visual +reference: + +```bash +curl -X POST https://api.sandbase.ai/api/v3/contents/generations/tasks \ + -H "Authorization: Bearer $SANDBASE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "bytedance/seedance/2.5-official", + "content": [ + { + "type": "text", + "text": "Create a cinematic product shot. Keep the bottle shape and label from the reference image." + }, + { + "type": "image_url", + "image_url": {"url": "asset://asset-20260710150403-hx4hf"}, + "role": "reference_image" + } + ], + "ratio": "16:9", + "resolution": "1080p", + "duration": 5, + "generate_audio": true + }' +``` + +The create response returns a task `id`. Poll +`GET /api/v3/contents/generations/tasks/{task_id}` as described on the selected model page. + +## Choose the content item and role + +| Asset type | `content[].type` | URL field | Supported role | Use it for | +| --- | --- | --- | --- | --- | +| Image | `image_url` | `image_url.url` | `first_frame` | Start the video from this exact frame | +| Image | `image_url` | `image_url.url` | `last_frame` | End on this frame; include a `first_frame` in the same request | +| Image | `image_url` | `image_url.url` | `reference_image` | Preserve a subject, product, composition, costume, or visual style | +| Video | `video_url` | `video_url.url` | `reference_video` | Follow motion, timing, camera work, or editing rhythm | +| Audio | `audio_url` | `audio_url.url` | `reference_audio` | Follow voice, dialogue, music, or sound design | + +Audio cannot be the only input. Combine a `reference_audio` Asset with text, an image, or a video. Any request that +contains a `video_url` uses the video-to-video billing rate. + +### Video Asset example + +```json +{ + "type": "video_url", + "video_url": {"url": "asset://asset-20260710150403-video1"}, + "role": "reference_video" +} +``` + +### Audio Asset example + +```json +{ + "type": "audio_url", + "audio_url": {"url": "asset://asset-20260710150403-audio1"}, + "role": "reference_audio" +} +``` + +## Direct URL or `asset://` reference? + +| Input | Best when | Trade-off | +| --- | --- | --- | +| Public HTTP(S) URL | The media is already hosted and used once | Fastest path, but the URL must remain reachable through task submission and provider fetch | +| `asset://` reference | The media is reused through the official Asset protocol | Adds a registration/readiness step, then gives a persistent reference for later Seedance tasks | + +For request parameters, polling, task statuses, and billing, continue with +[Seedance 2.5 Official](./seedance-2.5-official), [Seedance 2.0 Official](./seedance-2.0-official), or the complete +[Official Native API overview](/model-api-reference/official-native-api). diff --git a/model-api-reference/official-native-api/bytedance/seedance-2.0-official.md b/model-api-reference/official-native-api/bytedance/seedance-2.0-official.md index 69f51b99..350da7ad 100644 --- a/model-api-reference/official-native-api/bytedance/seedance-2.0-official.md +++ b/model-api-reference/official-native-api/bytedance/seedance-2.0-official.md @@ -14,6 +14,32 @@ bytedance/seedance/2.0-official Choose this lower-priced model when 480p or 720p output is sufficient. It supports text, image, video, and audio references using the same request structure as Seedance 2.5 Official. +## Use reusable media + +Seedance accepts public HTTP(S) references directly. It also supports the official-compatible Asset protocol: register +the media URL with `/v1/assets`, then pass the returned `asset://` reference through unchanged in the same native +`content` shape: + +```json +{ + "model": "bytedance/seedance/2.0-official", + "content": [ + {"type": "text", "text": "Keep the product appearance and add a slow cinematic camera orbit"}, + { + "type": "image_url", + "image_url": {"url": "asset://asset-20260710150403-hx4hf"}, + "role": "reference_image" + } + ], + "ratio": "16:9", + "resolution": "720p", + "duration": 5 +} +``` + +See [Media Assets for Seedance](./media-assets) for the complete registration, readiness, and generation +workflow, including image, video, and audio roles. + ## Create a task ```bash diff --git a/model-api-reference/official-native-api/bytedance/seedance-2.5-official.md b/model-api-reference/official-native-api/bytedance/seedance-2.5-official.md index 5de091e8..464e14f9 100644 --- a/model-api-reference/official-native-api/bytedance/seedance-2.5-official.md +++ b/model-api-reference/official-native-api/bytedance/seedance-2.5-official.md @@ -14,6 +14,32 @@ bytedance/seedance/2.5-official Choose this model when you need up to 1080p output. It supports 480p, 720p, and 1080p generation with text, image, video, and audio references. +## Use reusable media + +Seedance accepts public HTTP(S) references directly. It also supports the official-compatible Asset protocol: register +the media URL with `/v1/assets`, then pass the returned `asset://` reference through unchanged in the same native +`content` shape: + +```json +{ + "model": "bytedance/seedance/2.5-official", + "content": [ + {"type": "text", "text": "Keep the product appearance and add a slow cinematic camera orbit"}, + { + "type": "image_url", + "image_url": {"url": "asset://asset-20260710150403-hx4hf"}, + "role": "reference_image" + } + ], + "ratio": "16:9", + "resolution": "1080p", + "duration": 5 +} +``` + +See [Media Assets for Seedance](./media-assets) for the complete registration, readiness, and generation +workflow, including image, video, and audio roles. + ## Create a task ```bash diff --git a/model-api-reference/official-native-api/index.md b/model-api-reference/official-native-api/index.md index 0a927f79..a622e1bd 100644 --- a/model-api-reference/official-native-api/index.md +++ b/model-api-reference/official-native-api/index.md @@ -20,6 +20,7 @@ GPT Image 2 uses the native OpenAI Images API at `/v1/images/generations`. Pass - [Seedance 2.5 Official](/model-api-reference/official-native-api/bytedance/seedance-2.5-official) - [Seedance 2.0 Official](/model-api-reference/official-native-api/bytedance/seedance-2.0-official) +- [Media Assets for Seedance](/model-api-reference/official-native-api/bytedance/media-assets) ## Google diff --git a/scripts/validate-doc-content.mjs b/scripts/validate-doc-content.mjs index 75ce26a5..e9f57e5c 100644 --- a/scripts/validate-doc-content.mjs +++ b/scripts/validate-doc-content.mjs @@ -211,5 +211,22 @@ const nativeReference = readFileSync('model-api-reference/official-native-api/in assert.match(nativeReference, /`DELETE`\s*\|\s*`\/api\/v3\/contents\/generations\/tasks\/\{task_id\}`/, 'Official Native API must document task deletion') assert.match(nativeReference, /Cancel or remove a task/, 'Official Native API must explain task cancellation semantics') +const seedanceAssetReference = readFileSync('model-api-reference/official-native-api/bytedance/media-assets.md', 'utf8') +assert.match(seedanceAssetReference, /`POST \/v1\/assets`/, 'Seedance Asset guide must document Asset registration') +assert.match(seedanceAssetReference, /`GET \/v1\/assets\/\{external_id\}`/, 'Seedance Asset guide must document Asset readiness lookup') +assert.match(seedanceAssetReference, /asset:\/\/asset-/, 'Seedance Asset guide must use the persistent Asset reference in a generation request') +assert.match(seedanceAssetReference, /reference_image[\s\S]*reference_video[\s\S]*reference_audio/, 'Seedance Asset guide must map image, video, and audio roles') +assert.match(seedanceAssetReference, /official-compatible Asset protocol/, 'Seedance Asset guide must describe the official-compatible protocol boundary') +assert.match(seedanceAssetReference, /passed through unchanged/, 'Seedance Asset guide must state that asset references pass through unchanged') +assert.doesNotMatch(seedanceAssetReference, /\/v1\/upload/, 'Seedance official Asset guide must not mix in the generic upload endpoint') +assert.doesNotMatch(seedanceAssetReference, /SandBase Asset library/, 'Seedance Asset guide must not describe the compatible Asset protocol as a separate SandBase library') +assert.doesNotMatch(seedanceAssetReference, /POST \/api\/v3\/assets/, 'Seedance Asset guide must not expose the internal Asset gateway') + +for (const filename of ['seedance-2.5-official.md', 'seedance-2.0-official.md']) { + const seedanceModelReference = readFileSync(`model-api-reference/official-native-api/bytedance/${filename}`, 'utf8') + assert.match(seedanceModelReference, /Media Assets for Seedance/, `${filename} must link the Asset workflow`) + assert.match(seedanceModelReference, /asset:\/\/asset-/, `${filename} must show how to use a reusable Asset`) +} + assert.ok(inspected > 0, 'content validation did not inspect any public hand-written pages') console.log(`public hand-written content: ok (${inspected} pages)`) diff --git a/scripts/validate-public-api-surface.mjs b/scripts/validate-public-api-surface.mjs index 49482814..3504597f 100644 --- a/scripts/validate-public-api-surface.mjs +++ b/scripts/validate-public-api-surface.mjs @@ -671,6 +671,8 @@ assert.doesNotMatch(modelSidebar, /text: 'Official Native API'/, 'Model API main assert.match(officialNativeSidebar, /Official Native API/, 'Custom sidebar must expose Official Native API') assert.match(officialNativeSidebar, /official-native-api\/bytedance\/seedance-2\.5-official/, 'Official Native API sidebar must expose Seedance 2.5') assert.match(officialNativeSidebar, /official-native-api\/bytedance\/seedance-2\.0-official/, 'Official Native API sidebar must expose Seedance 2.0') +assert.match(officialNativeSidebar, /Media Assets for Seedance/, 'Official Native API sidebar must expose the Seedance Asset workflow') +assert.match(officialNativeSidebar, /official-native-api\/bytedance\/media-assets/, 'Official Native API sidebar must link the Seedance Asset workflow') assert.match(officialNativeSidebar, /Gemini Omni Flash Preview/, 'Official Native API sidebar must expose Gemini Omni') assert.match(officialNativeSidebar, /official-native-api\/google\/gemini-omni-flash-preview/, 'Official Native API sidebar must link Gemini Omni') assert.match(officialNativeSidebar, /Nano Banana Pro/, 'Official Native API sidebar must expose Gemini 3 Pro Image')