> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# SeeDance Videos Generation API Integrationsbeskrivning

> ByteDance Seedance Video Generation API guide - Ace Data Cloud

Detta dokument kommer att introducera en SeeDance Videos Generation API integrationsbeskrivning, som kan generera officiella SeeDance-videor genom att ange anpassade parametrar.

## Ansökningsprocess

För att använda SeeDance Videos Generation API, börja med att gå till [Ace Data Cloud-konsolen](https://platform.acedata.cloud/console/applications) för att hämta din API-token, som du ska spara.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

Om du inte har loggat in eller registrerat dig, kommer du automatiskt att omdirigeras till inloggningssidan för att registrera dig och logga in, och efter att ha slutfört detta kommer du automatiskt att återvända till den aktuella sidan.

**En API-token kan användas för att anropa alla tjänster på plattformen, utan att behöva ansöka separat för varje tjänst.** Första ansökan ger en gratis kvot för att prova; om kvoten tar slut kan du ladda på allmän balans i [konsolen](https://platform.acedata.cloud/console/coin).

> 📘 Fullständig dokumentation: [SeeDance Videos Generation API →](https://platform.acedata.cloud/documents/seedance-videos)

## Grundläggande användning

Först bör du förstå den grundläggande användningen, vilket innebär att du anger en prompt `content.text`, typ `content.type=text` samt modell `model`, för att få det bearbetade resultatet, detaljerna är som följer:

<p>
  <img src="https://cdn.acedata.cloud/seedance_parameters.png" width="500" className="m-auto" />
</p>

Här kan vi se att vi har ställt in Request Headers, inklusive:

* `accept`: vilken format av svar du vill ta emot, här anges som `application/json`, det vill säga JSON-format.
* `authorization`: nyckeln för att anropa API:et, som kan väljas direkt efter ansökan.

Dessutom har vi ställt in Request Body, inklusive:

* `model`: modellen för att generera videon.
  * **Seedance 1.x-serien**: `doubao-seedance-1-0-pro-250528`, `doubao-seedance-1-0-pro-fast-251015`, `doubao-seedance-1-5-pro-251215`, `doubao-seedance-1-0-lite-t2v-250428`, `doubao-seedance-1-0-lite-i2v-250428`.
  * **Seedance 2.0-serien** (stödjer ansikts-/karaktärsreferenser och andra multimodala indata): `doubao-seedance-2-0-260128` (standard), `doubao-seedance-2-0-fast-260128` (snabb), `doubao-seedance-2-0-mini-260615` (lätt). Se avsnittet "Ansikts- och karaktärsreferenser (Seedance 2.0)" nedan.
* `content`: indataarray, `type` kan vara `text` (prompt), `image_url` (referensbild), `audio_url` (referensljud, 2.0), `video_url` (referensvideo, 2.0). Bilder kan specificeras med `role`: `first_frame` (första bildruta) / `last_frame` (sista bildruta) / `reference_image` (ansikts-/karaktärs-/huvudreferens).
* `resolution`: utdataupplösning, valfritt `480p` / `720p` / `1080p` (2.0 standardmodell stöder även `4k`; 2.0:s `fast` / `mini` högst `720p`).
* `ratio`: bildförhållande, valfritt `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive`.
* `duration`: videolängd (sekunder), 1.x intervall 2–12, 2.0 intervall 2–15.
* `seed`: slumpmässig frö, heltal, -1 till 4294967295.
* `camerafixed`: om kameran ska vara fast, `true` / `false`.
* `watermark`: om vattenstämpel ska läggas till, `true` / `false`.
* `generate_audio`: om ljudvideo ska genereras, `true` / `false`, **endast `doubao-seedance-1-5-pro-251215` stöder**.
* `return_last_frame`: om den sista bildrutan av videon ska returneras i resultatet.
* `execution_expires_after`: tidsgräns för uppgiften (sekunder), intervall 3600–259200.
* `callback_url`: asynkron återkopplingsadress, efter inställning returnerar API:et omedelbart `task_id`, och när uppgiften är klar kommer resultatet att POST:as till den adressen.
* `async`: valfritt, sätts till `true` för att API:et omedelbart ska returnera `task_id`, utan att behöva ange `callback_url`, och sedan kan resultatet hämtas genom att pollera motsvarande uppgiftsfråge-API.

När du har valt kan du se att motsvarande kod också har genererats till höger, som visas i bilden:

<p>
  <img src="https://cdn.acedata.cloud/seedance_request.png" width="500" className="m-auto" />
</p>

Klicka på "Try" knappen för att testa, som visas i bilden ovan, här fick vi följande resultat:

```json theme={null}
{
  "success": true,
  "task_id": "9777f36b-4f44-47ff-962d-45cd2f7aeaa8",
  "trace_id": "ce5da2ca-6695-4459-9d2c-2ef9f86db752",
  "data": {
    "task_id": "7e4e1773-510a-4a73-9ab4-98dd1a0b2a7f",
    "status": "succeeded",
    "model": "doubao-seedance-2-0-fast-260128",
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "video_url": "https://platform2.cdn.acedata.cloud/seedance/036f24ed-a9b1-49b3-92c4-30049a3bc152.mp4"
  }
}
```

Det returnerade resultatet har flera fält, som beskrivs nedan:

* `success`, status för videogenereringsuppgiften.
* `task_id`, ID för videogenereringsuppgiften.
* `trace_id`, spårnings-ID för videogenereringen.
* `data`, resultatlistan för videogenereringsuppgiften.
  * `task_id`, server-ID för videogenereringsuppgiften.
  * `video_url`, videolänken för videogenereringsuppgiften.
  * `status`, status för videogenereringsuppgiften.
    * `model`, modellen som användes för att generera videon.

Vi kan se att vi har fått tillfredsställande videoinformation, vi behöver bara hämta den genererade SeeDance-videon baserat på videolänken i `data` i resultatet.

Om du dessutom vill generera motsvarande integrationskod kan du direkt kopiera den som genererats, till exempel CURL-koden nedan:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/seedance/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "content": [{"type":"text","text":"A white ceramic coffee mug on a glossy marble countertop with soft morning window light. The camera slowly orbits 360 degrees around the mug, steam gently rising."}],
  "model": "doubao-seedance-2-0-fast-260128",
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}'
```

## Inline parameterbeskrivning

I `content[].text` promptens slut kan du ange genereringsparametrar genom att lägga till `--parameter value` (gammal metod, svag validering, om felaktigt ifyllt används automatiskt standardvärden). Den fullständiga parameterlistan är som följer:

| In-line parameter | Corresponding field | Description                | Value range                                                   |
| ----------------- | ------------------- | -------------------------- | ------------------------------------------------------------- |
| `--rs`            | `resolution`        | Output resolution          | `480p` / `720p` / `1080p`                                     |
| `--rt`            | `ratio`             | Aspect ratio               | `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive` |
| `--dur`           | `duration`          | Video duration (seconds)   | 2–12                                                          |
| `--frames`        | `frames`            | Number of frames           | Integers satisfying 25+4n in \[29, 289]                       |
| `--fps`           | `framespersecond`   | Frame rate                 | Only supports `24`                                            |
| `--seed`          | `seed`              | Random seed                | -1 to 4294967295                                              |
| `--cf`            | `camerafixed`       | Whether to fix the camera  | `true` / `false`                                              |
| `--wm`            | `watermark`         | Whether to add a watermark | `true` / `false`                                              |

> **Recommended practice**: Use the corresponding top-level fields (such as `resolution`, `ratio`, etc.) directly in the Request Body for strict validation mode. If parameters are filled in incorrectly, a clear error message will be returned, making it easier to troubleshoot issues.

## Generate audio video

`doubao-seedance-1-5-pro-251215` supports generating videos with audio through the `generate_audio` parameter:

```json theme={null}
{
  "model": "doubao-seedance-1-5-pro-251215",
  "content": [
    {
      "type": "text",
      "text": "En flicka håller en räv, vinden blåser i hennes hår, du kan höra ljudet av vinden"
    }
  ],
  "generate_audio": true,
  "ratio": "16:9",
  "duration": 5
}
```

Other models do not support this parameter, and it will be ignored if passed.

## Image to video first frame

If you want to create a video from an image, the `content` parameter must first include an item with `type` as `image_url`, and the `image_url` field must be in object format: `{"url": "https://..."}` or Base64 format `{"url": "data:image/png;base64,..."}`.

> **Note**: `image_url` does not support being passed in string format (e.g., `"image_url": "https://..."`), it must use object format `"image_url": {"url": "https://..."}`, otherwise a 400 error will be returned.

Corresponding code:

```python theme={null}
import requests

url = "https://api.acedata.cloud/seedance/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "content": [
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/i2v_foxrgirl.png"
            }
        },
        {
            "type": "text",
            "text": "En flicka håller en räv i sina armar. Hon öppnar ögonen och ser ömt in i kameran, medan räven kärleksfullt håller tillbaka. När kameran långsamt drar sig tillbaka, blåser vinden försiktigt i hennes hår. --ratio adaptive  --dur 5"
        }
    ],
    "model": "doubao-seedance-1-0-pro-250528"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

When you click run, you will immediately get a result as follows:

```
{
    "success": true,
    "task_id": "dc7cceb5-3c12-4de7-a5f4-abcbba3e8e39",
    "trace_id": "b3b09de3-b7fa-4bb0-88b5-aad4b4a96fd4",
    "data": {
        "task_id": "cgt-20251222072003-x2259",
        "status": "succeeded",
        "video_url": "https://platform.cdn.acedata.cloud/seedance/6afb78b8-5ba8-424f-adcd-69423a700b50.mp4",
        "model": "doubao-seedance-1-0-pro-250528"
    }
}
```

You can see that the generated effect is an image-to-video creation, and the result is similar to the above.

## Image to video first and last frame

If you want to create a video with first and last frames from images, the `content` parameter must first include items of type `image_url`, and set `role` to `first_frame` and `last_frame`, allowing you to specify the following content:

* role: Specify first frame or last frame.
* image\_url
  * url Image link
    Additionally, `content` also needs to include an item of type `text` as a prompt.

Corresponding code:

```python theme={null}
import requests

url = "https://api.acedata.cloud/seedance/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
   "model": "doubao-seedance-1-0-pro-250528",
    "content": [
         {
            "type": "text",
            "text": "360-graders bild"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_first_frame.jpeg"
            },
            "role": "first_frame"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_last_frame.jpeg"
            },
            "role": "last_frame"
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

When you click run, you will immediately get a result as follows:

```
{
    "success": true,
    "task_id": "f7096c6c-9430-4392-8201-d259632d7afd",
    "trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a",
    "data": {
        "task_id": "cgt-20251222073134-54qcw",
        "status": "succeeded",
        "video_url": "https://platform.cdn.acedata.cloud/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4",
        "model": "doubao-seedance-1-0-pro-250528"
    }
}
```

You can see that the generated effect is character-generated video, and the result is similar to the above.

## Face and character reference (Seedance 2.0)

**Seedance 2.0 series** (`doubao-seedance-2-0-260128`, `doubao-seedance-2-0-fast-260128`, `doubao-seedance-2-0-mini-260615`) supports passing in "real person / character" reference materials: Add an item in `content` with `type` as `image_url` and `role` as `reference_image`, using a person's photo as a reference. The model will **maintain the appearance features** of that person in the generated video, thus placing the same person into a brand new scene, action, or shot.

> 📌 Real person photos will be automatically registered as underlying materials by the platform before being used for generation, and the entire process is completely transparent to the caller: **Request and response formats remain unchanged**, no additional parameters are required, and only the first generation will take a few extra seconds for material processing.

Usage points:

* Endast **Seedance 2.0-serien** modeller stödjer `reference_image`; 1.x-modeller, vänligen använd `first_frame` / `last_frame` (bild till video första och sista bild).
* `reference_image` **kan inte** användas tillsammans med `first_frame` / `last_frame`, endast en av dem kan väljas.
* Övre gräns för multimodala referenser: `image_url` högst **9** bilder; 2.0 stödjer också `audio_url` (med `role` som `reference_audio`, högst 3 stycken) och `video_url` (med `role` som `reference_video`, högst 3 stycken).
* Referensbilder rekommenderas att använda **en person, framifrån, tydlig, utan hinder** foton, ju tydligare ansiktet, desto högre likhet.

### Exempel ett: Närbild som behåller personens utseende

Skicka in ett foto av en ansikte, låt personen le och vinka mot kameran. Motsvarande kod:

```python theme={null}
import requests

url = "https://api.acedata.cloud/seedance/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "doubao-seedance-2-0-fast-260128",
    "content": [
        {
            "type": "text",
            "text": "Kvinnan tittar på kameran, ger ett varmt naturligt leende och vinkar med handen, mjukt studiobelysning, försiktig kameraframåtskjutning."
        },
        {
            "type": "image_url",
            "role": "reference_image",
            "image_url": {
                "url": "https://platform2.cdn.acedata.cloud/nanobanana/8e075897-0f50-4443-8500-666751791c6c.jpg"
            }
        }
    ],
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 5
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

Resultatet ser ut som följer, videon har personen som överensstämmer med referensbilden:

```json theme={null}
{
  "success": true,
  "task_id": "895eb5ea-bbe1-41a3-a9e9-48608e03f93a",
  "trace_id": "83544791-7a84-44de-b8d2-afe171a1c0e4",
  "data": {
    "task_id": "458abf29-cc39-4fd0-bcea-24f89a70d8de",
    "status": "succeeded",
    "video_url": "https://platform2.cdn.acedata.cloud/seedance/e71d3cc5-27e7-4719-be34-1f0e254eccaf.mp4",
    "model": "doubao-seedance-2-0-fast-260128",
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 5
  }
}
```

### Exempel två: Sätta samma person i en helt ny scen

Styrkan med `reference_image` ligger i att: endast **personens identitet** bevaras, medan scen, kläder och rörelser helt bestäms av prompten. Här används samma ansiktsfoto, låt personen bära en beige kappa och gå i en höstpark:

```json theme={null}
{
  "model": "doubao-seedance-2-0-fast-260128",
  "content": [
    {
      "type": "text",
      "text": "Samma kvinna i en beige kappa går genom en solig höstpark, gyllene löv faller runt henne, hon ler mjukt mot kameran, filmisk följande bild."
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://platform2.cdn.acedata.cloud/nanobanana/8e075897-0f50-4443-8500-666751791c6c.jpg"
      }
    }
  ],
  "resolution": "720p",
  "ratio": "9:16",
  "duration": 5
}
```

Resultatet ser ut som följer, personens utseende bevaras, medan scenen har bytts till en höstpark:

```json theme={null}
{
  "success": true,
  "task_id": "00872de7-16b7-431f-b4f7-6bf38ae86157",
  "trace_id": "577a07c3-4f5f-4cc7-86fe-535bb8332614",
  "data": {
    "task_id": "32fe1537-ba3e-452a-8749-3ef8890d37fd",
    "status": "succeeded",
    "video_url": "https://platform2.cdn.acedata.cloud/seedance/44f47593-556b-4fda-afa5-7a71eefcd228.mp4",
    "model": "doubao-seedance-2-0-fast-260128",
    "resolution": "720p",
    "ratio": "9:16",
    "duration": 5
  }
}
```

> 💡 Om du vill att personen exakt ska återspegla kompositionen i fotot (och inte "en annan scen med samma person"), kan du använda `first_frame` (bild till video första bild), så att videon börjar röra sig från denna bild.

## Asynkron callback

Eftersom SeeDance Videos Generation API:s genereringstid är lång (ungefär 1-2 minuter), kan du använda `callback_url`-fältet för att använda asynkron läge, för att undvika att HTTP-anslutningen upptar lång tid.

Övergripande process: Klienten initierar en begäran och anger `callback_url`, API:n returnerar omedelbart ett svar som innehåller `task_id`; när uppgiften är klar, skickar plattformen de genererade resultaten i POST JSON-format till `callback_url`, resultatet innehåller också `task_id` för att möjliggöra koppling.

```json theme={null}
{
  "task_id": "f7096c6c-9430-4392-8201-d259632d7afd"
}
```

När uppgiften är klar, ser innehållet som plattformen skickar till `callback_url` ut som följer:

```json theme={null}
{
  "success": true,
  "task_id": "f7096c6c-9430-4392-8201-d259632d7afd",
  "trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a",
  "data": {
    "task_id": "cgt-20251222073134-54qcw",
    "status": "succeeded",
    "video_url": "https://platform.cdn.acedata.cloud/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4",
    "model": "doubao-seedance-1-0-pro-250528"
  }
}
```

Fältet `task_id` i resultatet är detsamma som det som returnerades vid begäran, genom detta fält kan uppgiften kopplas.

## Felhantering

Vid anrop av API:n, om ett fel uppstår, kommer API:n att returnera motsvarande felkod och information. Till exempel:

* `400 token_mismatched`: Felaktig begäran, möjligtvis på grund av saknade eller ogiltiga parametrar.
* `400 api_not_implemented`: Felaktig begäran, möjligtvis på grund av saknade eller ogiltiga parametrar.
* `401 invalid_token`: Obefogad, ogiltig eller saknad auktoriseringstoken.
* `429 too_many_requests`: För många begärningar, du har överskridit hastighetsgränsen.
* `500 api_error`: Intern serverfel, något gick fel på servern.

### Exempel på felrespons

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## Slutsats

Genom detta dokument har du fått en förståelse för hur man använder SeeDance Videos Generation API för att generera video genom promptar, referensbilder, samt Seedance 2.0:s ansikts-/rollreferenser. Vi hoppas att detta dokument kan hjälpa dig att bättre integrera och använda API:n. Om du har några frågor, tveka inte att kontakta vårt tekniska supportteam.