Integreringsguide för Flux Videos API

Flux Videos API använder POST /flux/videos för videogenerering, bild-till-video med nyckelbilder, videofortsättning och utkastförbättring. action=generate (standard), mode väljer genereringsläge; för att fråga resultat används enhetligt den befintliga POST /flux/tasks.

För närvarande Beta. Text-till-video, bild-till-video, videofortsättning och utkastförbättring är tillgängliga. HTTP 200 och uppgifts-ID innebär endast att uppgiften har accepterats; du måste fortsätta fråga efter slutresultatet.

1. Hämta API Token

Registrera eller logga in på Ace Data Cloud-konsolen, skapa en applikation och hämta API Token. En generell API Token kan anropa plattformstjänster; bekräfta att applikationen har behörighet att anropa Flux-tjänsten och tillgängligt saldo.
Se paket och priser för varje åtgärd på Flux-tjänstsidan. När saldot är otillräckligt, fyll på på konsolens saldosida.
Begäran använder Authorization: Bearer <din Token>. Token ska lagras i miljövariabler på serversidan och får inte skrivas i frontend-sidor, offentliga kodförråd, skärmbilder eller callback-URL:er.

Koden i denna artikel läser enhetligt miljövariabler:

export ACEDATACLOUD_API_TOKEN='替换为你自己的 API Token'

Objekt	Värde
API-rotadress	`https://api.acedata.cloud`
Skicka videouppgift	`POST /flux/videos`
Fråga befintlig uppgift	`POST /flux/tasks`
Autentisering	`Authorization: Bearer $ACEDATACLOUD_API_TOKEN`
Begärandeformat	`Content-Type: application/json`

För fullständiga fält och onlinedebuggning, se Flux Videos API, och för uppgiftsfrågor, se Flux Tasks API.

2. Välj åtgärd och indata

action	mode	Indata	Resultat
`generate` (standardvärdet när action utelämnas)	`t2v`	`prompt`	Generera video från text
`generate`	`i2v`	`prompt`、`keyframes`	Generera video från en eller flera nyckelbilder
`generate`	`v2v`	`prompt`、`start_video`	Fortsätt baserat på inmatad video
`generate`	`draft_enhance`	`draft_task_id` för ditt färdigställda utkast	Förbättra detta utkast

Genereringsmodellen är flux-3, och action är generate (standard). Välj text-till-video, bild-till-video, videofortsättning eller utkastförbättring via mode.

Gemensamma genereringsparametrar

Parameter	Beskrivning
`mode`	Obligatorisk; `t2v`, `i2v`, `v2v` eller `draft_enhance`
`prompt`	Obligatorisk för vanlig generering; utkastförbättring tillåter inte att den ursprungliga prompten skrivs över
`duration`	t2v/i2v är heltal på 5–20 sekunder, v2v är heltal på 5–15 sekunder, eller `auto`; den slutliga utdatalängden kan avvika något från det begärda värdet
`resolution`	`hd`, `fhd`, `qhd`, `uhd`; vanlig generering har standardvärdet `hd`, utkastförbättring har standardvärdet `fhd`
`aspect_ratio`	`auto`, `21:9`, `2:1`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `9:21`
`draft`	Om ett utkast först ska genereras; utkast stöder endast `hd`
`generate_audio`	Om synkroniserat ljud ska genereras; `false` är ett giltigt värde, behåll explicit booleskt värde
`safety_tolerance`	Valfri; heltal från 0–4
`async`	Rekommenderas att sättas till `true`, returnerar plattformsuppgifts-ID direkt och frågar sedan resultaten
`callback_url`	Valfri; HTTP(S)-adress som tar emot slutligt JSON-resultat; när den är inställd accepteras uppgiften också asynkront

Material-URL:er måste kunna läsas av tjänsten. Om tillfälliga signerade URL:er används, ska tillräcklig giltighetstid reserveras för nedladdning och bearbetning. Använd inte webbsidesadresser som bild- eller videofiladresser.

3. Text-till-video: fullständiga testade begäranden och resultat

Följande begäran kördes framgångsrikt i produktionsgränssnittet före prisjusteringen 2026-10-02. Att utelämna action verifierade standardbeteendet för generering; async=true undviker lång väntan på HTTP-anslutningen.

curl -X POST 'https://api.acedata.cloud/flux/videos' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "flux-3",
    "mode": "t2v",
    "prompt": "A small toy sailboat floating on calm blue water in warm morning light, steady camera, no text.",
    "duration": 5,
    "resolution": "hd",
    "draft": true,
    "async": true
  }'

Acceptanssvar (verkligt uppgifts-ID):

{
  "task_id": "4341eb66-3845-4972-bb86-712a6cfae845",
  "trace_id": "b0f851bd-0925-43ca-acc3-6f634c70d607"
}

Spara task_id från ditt eget svar och fortsätt fråga; använd inte uppgifts-ID:n från dokumentationsexempel för att fråga efter resultat från andra konton.

curl -X POST 'https://api.acedata.cloud/flux/tasks' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"action":"retrieve","id":"替换为本次返回的 task_id"}'

Fältet response som returneras av uppgiftsfrågan innehåller det slutliga affärsresultatet. Nedan är den framgångsrikt testade response för denna gång, där den yttre uppgiftsmetadatan har utelämnats. Video-URL:en i dokumentationen har ersatts med en kopia av samma fil på ett långvarigt exempel-CDN (SHA-256 är identisk); faktiska anrop returnerar resultats-URL:en för denna uppgift:

{
  "success": true,
  "task_id": "4341eb66-3845-4972-bb86-712a6cfae845",
  "trace_id": "b0f851bd-0925-43ca-acc3-6f634c70d607",
  "data": [
    {
      "id": "4341eb66-3845-4972-bb86-712a6cfae845",
      "model": "flux-3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/flux/4341eb66-3845-4972-bb86-712a6cfae845-5f4391e1942c.mp4",
      "seconds": 5.041667,
      "width": 1280,
      "height": 704,
      "fps": 24,
      "draft_task_id": "4341eb66-3845-4972-bb86-712a6cfae845"
    }
  ],
  "usage": {
    "action": "generate",
    "seconds": 5.041667,
    "output_mp_seconds": 4.3326825781250005,
    "mode": "t2v",
    "resolution": "hd",
    "draft": true
  },
  "cost": {
    "amount": 2.6884689277500002,
    "currency": "credit",
    "list_amount": 2.9871876975000005
  }
}

Visa denna testade video. Mediekontroll bekräftar att utdata är en MP4 på 1280×704, 24 fps och 5.041667 sekunder, med en filstorlek på 2,607,276 byte.

Svarsfält	Användning
`success`	Om den slutliga uppgiften lyckades; att task_id returneras i mottagningsfasen är inte lika med success=true
`task_id`	Plattformens uppgifts-ID, används för polling och idempotent behandling i verksamheten
`trace_id`	Tillhandahålls till supportpersonal vid felsökning
`data[].video_url`	Läsbar adress till videoresultatet
`data[].seconds/width/height/fps`	Faktisk utdatalängd, storlek och bildfrekvens uppmätt av servern
`data[].draft_task_id`	Indata-ID för utkastförbättring; visas endast när ett återanvändbart utkast returneras
`usage`	Slutlig fakturerad användning; använd inte begärd duration för att skriva över faktiska seconds
`cost.amount`	Credits som slutligen dras denna gång; `currency=credit` är inte USD
`cost.list_amount`	Credits före konsumentrabatt för appanvändare; returneras när tillämpligt

Detta är ett historiskt test före prisjusteringen: list_amount=2.9871876975 Credits, kontot hade då 10 % konsumentrabatt, och faktiskt amount=2.68846892775 Credits. Det nya priset den 2026-10-02 har sänkts med cirka 6.33 %; samma utkast på 5.041667 sekunder kostar enligt nuvarande pris 2.798125185 Credits (före konsumentrabatt), eller 2.5183126665 Credits om 10 % konsumentrabatt fortfarande gäller. Fakturor för historiska uppgifter räknas inte om. Andra kontons abonnemang och rabatter kan skilja sig; detta är inte ett fast pris i USD för alla användare.

4. Bild-till-video: vanlig och med tidsbestämda nyckelrutor

Nedan följer parameterexempel där material-URL:er behöver ersättas; detta är inte ett påstående om att exemplet redan har körts framgångsrikt. Efter att genereringen är klar, fråga enligt processen ovan; resultatstrukturen är densamma. En eller två bilder använder en vanlig array:

{
  "action": "generate",
  "model": "flux-3",
  "mode": "i2v",
  "prompt": "The camera slowly moves around the product in soft studio light.",
  "keyframes": [
    "https://example.com/first-frame.jpg"
  ],
  "duration": 5,
  "resolution": "hd",
  "generate_audio": false,
  "async": true
}

När tidpunkter för nyckelrutor anges, använd par av [sekunder, bild-URL]:

{
  "action": "generate",
  "model": "flux-3",
  "mode": "i2v",
  "prompt": "A smooth transition from morning light to a warm sunset.",
  "keyframes": [[0, "https://example.com/start.jpg"], [5, "https://example.com/end.jpg"]],
  "duration": 5,
  "resolution": "hd",
  "async": true
}

1–10 nyckelrutor tillåts. Arrayer med tid måste vara i stigande tidsordning, tiden är 0–20 sekunder, och vanliga URL:er och tidsbestämda poster får inte blandas. Tre eller fler vanliga nyckelrutor måste uttryckligen ange duration och kan inte använda auto.

Testat resultat för bild-till-video

Den matchande inmatningen för detta test är följande (endast beskrivande text används i stället för fullständig base64, övriga fält är den verkliga begäran):

{
  "async": true,
  "action": "generate",
  "model": "flux-3",
  "prompt": "The toy sailboat drifts slowly across calm water. A steady camera, gentle daylight, no people or text.",
  "duration": 5,
  "resolution": "hd",
  "generate_audio": false,
  "draft": false,
  "mode": "i2v",
  "keyframes": [
    "<下图 PNG 文件的原始 base64 字符串>"
  ]
}

Referensnyckelruta för denna bild-till-video

Efter att ha laddat ned denna PNG-nyckelruta kan Python base64.b64encode(image_bytes).decode("ascii") användas för att få den ursprungliga strängen och placera den i keyframes-arrayen. Använd inte den beskrivande texten i dokumentet som bildindata. Följande är det verkliga slutliga response för en produktionsuppgift den 2026-10-01 (inte ett simulerat svar); endast video-URL:en har bytts ut mot en långsiktig exempelkopia med samma hash. Testinmatningen använder den ursprungliga base64-strängen för en PNG på 1280×720 som en enda nyckelruta; URL-indatan ovan är ett separat parameterexempel.

{
  "success": true,
  "task_id": "b1106de8-d586-4e23-b489-381e2f86a10f",
  "trace_id": "f62d5c56-cfb2-4f8f-b339-ef019d4c0d10",
  "data": [
    {
      "id": "b1106de8-d586-4e23-b489-381e2f86a10f",
      "model": "flux-3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/flux/b1106de8-d586-4e23-b489-381e2f86a10f-bef14458cc9d.mp4",
      "seconds": 5.041667,
      "width": 1280,
      "height": 704,
      "fps": 24
    }
  ],
  "usage": {
    "action": "generate",
    "seconds": 5.041667,
    "output_mp_seconds": 4.3326825781250005,
    "mode": "i2v",
    "resolution": "hd",
    "draft": false
  },
  "cost": {
    "amount": 7.617328628625,
    "currency": "credit",
    "list_amount": 8.46369847625
  }
}

Visa testvideo。

5. Videofortsättning

start_video skickar in adressen till en befintlig videofil, mode=v2v, med en längd på högst 15 sekunder.

{
  "action": "generate",
  "model": "flux-3",
  "mode": "v2v",
  "prompt": "Continue the sailboat drifting forward with the same steady camera.",
  "start_video": "https://example.com/source.mp4",
  "duration": 5,
  "resolution": "hd",
  "async": true
}

Testutdata för videofortsättning

Den fullständiga testinmatningen denna gång är följande; vid reproduktion av utkastförbättring måste den ersättas med ditt eget utkast-ID. Materialets URL använder en långsiktig exempelkopiering av samma fil:

{
  "action": "generate",
  "model": "flux-3",
  "mode": "v2v",
  "start_video": "https://cdn.acedata.cloud/assets/examples/flux/b41293be-94c0-4dc7-9f39-ce04f0a8798d-c055a3079059.mp4",
  "prompt": "Continue the same sailboat drifting gently across calm water in the same continuous steady shot.",
  "duration": 5,
  "resolution": "hd",
  "generate_audio": false,
  "async": true
}

Följande är det verkliga slutliga response från produktionsuppgiften 2026-10-01 (inte ett simulerat svar); endast video-URL:en har bytts ut mot en långsiktig exempelkopiering med samma hash.

{
  "success": true,
  "task_id": "8af9aa42-7e4d-47a4-bd61-144d97440c91",
  "trace_id": "4fb49afc-abca-4039-bbaa-adb66e293544",
  "data": [
    {
      "id": "8af9aa42-7e4d-47a4-bd61-144d97440c91",
      "model": "flux-3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/flux/8af9aa42-7e4d-47a4-bd61-144d97440c91-a512d6574811.mp4",
      "seconds": 5,
      "width": 1280,
      "height": 704,
      "fps": 24
    }
  ],
  "usage": {
    "action": "generate",
    "seconds": 5,
    "output_mp_seconds": 4.296875,
    "mode": "v2v",
    "resolution": "hd",
    "draft": false
  },
  "cost": {
    "amount": 18.219375,
    "currency": "credit",
    "list_amount": 20.24375
  }
}

Visa testvideo。 Testinmatningens start_video är den slutförda utkastvideon, övriga parametrar är duration=5、resolution=hd、generate_audio=false。

6. Först utkast, sedan förbättring

Använd draft=true、resolution=hd för att generera ett utkast och vänta på att det lyckas.
Hämta plattformens utkast-ID från slutliga data[0].draft_task_id.
Skicka en förbättringsbegäran med applikationsuppgifter som har samma tillhörighet:

{
  "action": "generate",
  "model": "flux-3",
  "mode": "draft_enhance",
  "draft_task_id": "Ersätt med ditt eget slutförda utkast-ID",
  "resolution": "fhd",
  "async": true
}

Utkastförbättring kan inte skicka in prompt、duration、aspect_ratio、version、generate_audio、draft、keyframes、start_video för att skriva över det ursprungliga innehållet. Utkastcachen är en tillfällig resurs, förbättra den i tid; permanent lagring eller ett fast antal lagringsdagar garanteras inte. Utkast som inte tillhör dig/den aktuella applikationen, ofullständiga utkast och utgången cache kan inte återanvändas. Utkast och förbättring är två uppgifter och debiteras separat efter lyckad körning.

Testutdata för utkastförbättring

{
  "action": "generate",
  "model": "flux-3",
  "mode": "draft_enhance",
  "draft_task_id": "b41293be-94c0-4dc7-9f39-ce04f0a8798d",
  "resolution": "hd",
  "async": true
}

Följande är det verkliga slutliga response från produktionsuppgiften 2026-10-01 (inte ett simulerat svar); endast video-URL:en har bytts ut mot en långsiktig exempelkopiering med samma hash.

{
  "success": true,
  "task_id": "1db6243b-4a05-4484-828c-25bb17de7108",
  "trace_id": "64f93fa1-8d18-4c8b-a6d2-888009eb7cfa",
  "data": [
    {
      "id": "1db6243b-4a05-4484-828c-25bb17de7108",
      "model": "flux-3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/flux/1db6243b-4a05-4484-828c-25bb17de7108-058d92166607.mp4",
      "seconds": 5.041667,
      "width": 1280,
      "height": 704,
      "fps": 24
    }
  ],
  "usage": {
    "action": "generate",
    "seconds": 5.041667,
    "output_mp_seconds": 4.3326825781250005,
    "mode": "t2v",
    "resolution": "hd",
    "draft": false
  },
  "cost": {
    "amount": 7.617328628625,
    "currency": "credit",
    "list_amount": 8.46369847625
  }
}

Visa testvideo。 Testinmatningen är ditt eget draft_task_id=b41293be-94c0-4dc7-9f39-ce04f0a8798d、resolution=hd；slutliga usage.mode=t2v anger det ursprungliga utkastläget. Denna uppgift debiteras separat från det ursprungliga utkastet.

7. Python-anrop från början till slut

Installera requests, ange din egen Token och kör skriptet nedan för att slutföra ”skicka in en gång → polla → mata ut video-URL”. Både förfrågningar och nätverksåterförsök bör använda det ursprungliga task_id för att undvika att betalda uppgifter skickas in flera gånger.

import os
import time
import requests

base_url = "https://api.acedata.cloud"
headers = {
    "Authorization": "Bearer " + os.environ["ACEDATACLOUD_API_TOKEN"],
    "Accept": "application/json",
}
payload = {
    "action": "generate",
    "model": "flux-3",
    "mode": "t2v",
    "prompt": "A small toy sailboat floating on calm blue water in warm morning light.",
    "duration": 5,
    "resolution": "hd",
    "draft": True,
    "async": True,
}
submitted = requests.post(base_url + "/flux/videos", json=payload, headers=headers, timeout=120)
submitted.raise_for_status()
accepted = submitted.json()
if accepted.get("error"):
    raise RuntimeError(accepted["error"])
task_id = accepted["task_id"]
print("Task ID:", task_id)  # 持久化保存，用于恢复轮询

# 30 分钟是本示例的客户端等待上限，不是服务的完成时限承诺。
deadline = time.monotonic() + 30 * 60
while time.monotonic() < deadline:
    polled = requests.post(
        base_url + "/flux/tasks",
        json={"action": "retrieve", "id": task_id},
        headers=headers,
        timeout=30,
    )
    polled.raise_for_status()
    task = polled.json()
    if task.get("error"):
        raise RuntimeError(task["error"])
    result = task.get("response") or task.get("result")
    if isinstance(result, dict) and result.get("success") is True:
        print("Video:", result["data"][0]["video_url"])
        print("Usage:", result.get("usage"))
        print("Cost:", result.get("cost"))
        break
    if isinstance(result, dict) and result.get("error"):
        raise RuntimeError(result["error"])
    time.sleep(10)
else:
    raise TimeoutError("Still processing; resume polling with task_id=" + task_id)

Efter en nätverkstimeout ska du inte betrakta en okänd status som ett fel och omedelbart skicka in på nytt. Om task_id redan har erhållits, fortsätt att fråga efter uppgiften; registrera task_id och trace_id för att underlätta felsökning. Själva pollinggränssnittet medför inga genereringsavgifter.

8. Använda callback

Lägg till callback_url vid inskickning; när uppgiften är klar kommer slutligt JSON-resultat att POST:as till denna adress. Framgångsstrukturen är densamma som den tidigare response, medan fel inkluderar error.

{
  "action": "generate",
  "model": "flux-3",
  "mode": "t2v",
  "prompt": "A small sailboat on calm water.",
  "duration": 5,
  "resolution": "hd",
  "draft": true,
  "callback_url": "https://your-server.example/flux-callback"
}

Callback-adressen ska vara åtkomlig från det offentliga nätverket. Efter att ha mottagit en avisering, behandla den idempotent enligt task_id och returnera 2xx så snart som möjligt; affärsbearbetning kan köas. Detta dokument anger inte att callbacken har signaturautentisering: före känsliga åtgärder såsom tilldelning av affärsförmåner, använd din egen Token för att fråga samma uppgift och verifiera resultatet. Om callbacken inte tas emot kan du fortfarande fortsätta att polla, och ska inte generera på nytt.

9. Aktuell fakturering och prislista

Uppdaterad 2026-10-02: Enhetspriserna för varje nivå i detta videogränssnitt har sänkts med cirka 6,33 %, medan mätsätt, paket och regler för konsumtionsrabatter förblir oförändrade. cost i de historiska faktiska response-exemplen ovan är fakturan när uppgiften slutfördes och representerar inte aktuell prissättning. Videogenerering debiteras efter faktiskt antal sekunder i utdata. Nedan visas aktuella enhetspriser i Credits utan tillämpad kontoförbrukningsrabatt, i enlighet med reglerna på Flux-prissidan.

Åtgärd/läge	Upplösning	Enhetspris i Credits
t2v / i2v-utkast	hd	0.555 / sekund
v2v-utkast	hd	1.11 / sekund
t2v / i2v / motsvarande utkastsförbättring	hd	1.5725 / sekund
Samma som ovan	fhd	2.6825 / sekund
Samma som ovan	qhd	3.7 / sekund
Samma som ovan	uhd	7.4 / sekund
v2v / motsvarande utkastsförbättring	hd	3.7925 / sekund
Samma som ovan	fhd	4.9025 / sekund
Samma som ovan	qhd	6.0125 / sekund
Samma som ovan	uhd	8.7875 / sekund

Omräkning till USD: faktisk kostnad (USD) = cost.amount (Credits) × paketets price / paketets amount. Påfyllningsnivåer och konsumtionsrabatter påverkar det faktiska priset; Credits kan inte direkt likställas med USD. Misslyckade uppgifter debiteras inga genereringsavgifter; slutbeloppet avgörs av slutföranderesultatet och anropsposterna i konsolen.

10. Vanliga frågor och felsökning

Situation	Rekommendation
Parameterfel (400)	Kontrollera action=generate, mode, duration och nyckelbildsformat; blanda inte fält från olika genereringslägen
Autentiseringsfel (401)	Kontrollera Bearer Token, appbehörigheter och om autentiseringsuppgifterna är giltiga
Avslag vid innehållsgranskning (403)	Anpassa material och promptar, och skicka inte upprepade gånger in exakt samma innehåll
Hastighetsbegränsning (429)	Minska samtidigheten och försök igen med backoff
service_unavailable (503)	Den aktuella åtgärden är inte tillgänglig; redan accepterade asynkrona uppgifter kan rapportera detta fel i den slutliga response
task_id har returnerats men videon saknas fortfarande	Fortsätt fråga efter response och betrakta inte HTTP 200 som att genereringen är slutförd
Utkast kan inte återanvändas	Bekräfta rätt användare/aktuell app, att uppgiften är slutförd, att den ursprungliga begäran hade draft=true, och kontrollera om den tillfälliga cachen fortfarande är giltig

Vid återkoppling, ange task_id, trace_id, begärandetid och maskerade parametrar; skicka inte API Token. Se Flux MCP-integrationsguiden för fler metoder.

Getting Started

AI Samtal

AI Bild

AI Video

AI Ljud

Web & Data

CAPTCHA

Identitet

Coding

Fler guider

Integreringsguide för Flux Videos API

1. Hämta API Token

2. Välj åtgärd och indata

Gemensamma genereringsparametrar

3. Text-till-video: fullständiga testade begäranden och resultat

4. Bild-till-video: vanlig och med tidsbestämda nyckelrutor

Testat resultat för bild-till-video

5. Videofortsättning

Testutdata för videofortsättning

6. Först utkast, sedan förbättring

Testutdata för utkastförbättring

7. Python-anrop från början till slut

8. Använda callback

9. Aktuell fakturering och prislista

10. Vanliga frågor och felsökning

​1. Hämta API Token

​2. Välj åtgärd och indata

​Gemensamma genereringsparametrar

​3. Text-till-video: fullständiga testade begäranden och resultat

​4. Bild-till-video: vanlig och med tidsbestämda nyckelrutor

​Testat resultat för bild-till-video

​5. Videofortsättning

​Testutdata för videofortsättning

​6. Först utkast, sedan förbättring

​Testutdata för utkastförbättring

​7. Python-anrop från början till slut

​8. Använda callback

​9. Aktuell fakturering och prislista

​10. Vanliga frågor och felsökning

1. Hämta API Token

2. Välj åtgärd och indata

Gemensamma genereringsparametrar

3. Text-till-video: fullständiga testade begäranden och resultat

4. Bild-till-video: vanlig och med tidsbestämda nyckelrutor

Testat resultat för bild-till-video

5. Videofortsättning

Testutdata för videofortsättning

6. Först utkast, sedan förbättring

Testutdata för utkastförbättring

7. Python-anrop från början till slut

8. Använda callback

9. Aktuell fakturering och prislista

10. Vanliga frågor och felsökning