Zum Hauptinhalt springen
POST
/
v1
/
videos
/
generations
curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "happyhorse-1.0",
    "prompt": "A little girl walking down the road, cinematic feel",
    "resolution": "1080P",
    "size": "16:9",
    "duration": 5,
    "seed": 42
  }'
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01J9HA7JPQ9A0Z6JZ3V8M9W6PZ"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt

Use this file to discover all available pages before exploring further.

curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "happyhorse-1.0",
    "prompt": "A little girl walking down the road, cinematic feel",
    "resolution": "1080P",
    "size": "16:9",
    "duration": 5,
    "seed": 42
  }'
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01J9HA7JPQ9A0Z6JZ3V8M9W6PZ"
    }
  ]
}

Autorisierung

Authorization
string
erforderlich
Alle API-Endpunkte erfordern eine Bearer-Token-AuthentifizierungAPI-Key abrufen:Besuchen Sie die Seite zur API-Key-Verwaltung, um Ihren API-Key zu erhaltenFügen Sie ihn zum Request-Header hinzu:
Authorization: Bearer YOUR_API_KEY

Modus-Routing

happyhorse-1.0 ist der einheitliche Einstieg für Text-to-Video / Image-to-Video / Reference-Image-to-Video / Video Edit. Das Backend ermittelt den Modus automatisch anhand der eingehenden Parameter. Alle Modi werden nach derselben Regel abgerechnet (nur Auflösung × Sekunden):
Übergebene FelderRoutet zuModusbeschreibung
Nur promptText-to-Video (T2V)Video rein aus Text generieren
prompt + first_frame_imageImage-to-Video (I2V)Animation aus einem Erstbild
prompt + image_urls (1–9 Bilder)Reference-Image-to-Video (R2V)Neue Szene aus Referenzbildern generieren
prompt + video_url (optional image_urls 0–5 als Stilreferenzen / audio_setting)Video Edit (EDIT)Quellvideo umschreiben / umstilisieren
Routing-Priorität (hoch nach niedrig): video_url > first_frame_image > image_urls > nur prompt. Regeln zur gegenseitigen Ausschließlichkeit: Die drei Medienfelder (first_frame_image / image_urls / video_url) sind paarweise gegenseitig ausschließend. Die einzige gültige Kombination ist video_url + image_urls (EDIT-Modus + Referenzbilder). Werden zwei sich ausschließende Felder übergeben, wird 400 mixed_media_not_allowed zurückgegeben.

Anfrageparameter

model
string
erforderlich
Name des Videogenerierungsmodells, fest auf happyhorse-1.0
prompt
string
Beschreibung des Videoinhalts, bis zu 2500 Zeichen; darf keine Sondertoken enthalten
  • T2V- / R2V- / EDIT-Modi: erforderlich
  • I2V-Modus: optional, aber empfohlen zur Steuerung von Kamerabewegung und Aktionen
Beispiel: "A little girl walking down the road, cinematic feel"
first_frame_image
string
Erstes Einzelbild, löst I2V (Image-to-Video) aus. Unterstützt URL oder base64 (data:image/<mime>;base64,<payload>, das Gateway lädt es automatisch in OSS hoch)Schließt sich gegenseitig aus mit image_urls / video_url
Anforderungen an das Erstbild:
  • Format: JPEG / JPG / PNG / BMP / WEBP
  • Kurze Seite: ≥ 300 px
  • Seitenverhältnis: 1:2.5 bis 2.5:1
  • Dateigröße: ≤ 10 MB
image_urls
array<string>
Bilder-Array:
  • R2V-Modus (nur image_urls angegeben): 1–9 Bilder, dienen als Subjekt-/Stilreferenzen zur Generierung einer neuen Szene
  • EDIT-Modus (zusammen mit video_url angegeben): 0–5 Bilder, dienen als Stilreferenz
Unterstützt URL oder base64Schließt sich gegenseitig aus mit first_frame_image; kann mit video_url kombiniert werden
Anforderungen an Referenzbilder:
  • Format: JPEG / JPG / PNG / BMP / WEBP
  • Kurze Seite: empfohlen ≥ 720p
  • Seitenverhältnis: kurz / lang ≥ 0,4
  • Dateigröße: ≤ 10 MB
  • Anzahl: R2V muss 1–9 sein; EDIT bis zu 5
video_url
string
URL des Quellvideos, löst EDIT (Video Edit) aus. Base64 wird nicht unterstützt — geben Sie einen HTTP/HTTPS-Direktlink anSchließt sich gegenseitig aus mit first_frame_image; kann mit image_urls (≤ 5) kombiniert werden
Anforderungen an das Quellvideo:
  • Dauer: 3–60 Sekunden (> 15s wird vom Upstream automatisch von 0 bis 15s gekürzt)
  • Auflösung: mindestens 480p, kurze Seite ≥ 360
  • Seitenverhältnis: 1:8 bis 8:1
  • Format: MP4 / MOV (H.264 empfohlen)
  • Bildrate: > 8 fps
  • Dateigröße: ≤ 100 MB
Im EDIT-Modus entspricht die Dauer des generierten Videos der Dauer des Quellvideos (begrenzt auf die gekürzten 15s, wenn die Quelle länger ist). Der Parameter duration hat hier keine Wirkung. Um die Ausgabelänge zu steuern, schneiden Sie das Quellvideo vor dem Hochladen auf die Zieldauer.
audio_setting
string
Standard:"auto"
Audio-Einstellung, nur im EDIT-Modus wirksam (video_url muss übergeben werden)Optionen:
  • auto – Audio automatisch generieren (Standard)
  • origin – Audiospur des Quellvideos beibehalten
Wird dieses Feld außerhalb des EDIT-Modus übergeben, wird 400 audio_setting_only_for_edit zurückgegeben
resolution
string
Standard:"1080P"
Videoauflösung (beeinflusst die Abrechnung)Optionen:
  • 720P – Standard
  • 1080P – Hohe Auflösung (Standard)
duration
integer
Standard:"5"
Videodauer in Sekunden (beeinflusst die Abrechnung)Unterstützter Bereich: jede Ganzzahl von 3 bis 15Standard: 5
Hat im EDIT-Modus keine Wirkung (wenn video_url angegeben ist): Die Dauer des generierten Videos entspricht der des Quellvideos (Abrechnung nach den gekürzten 15s, wenn die Quelle länger als 15s ist). Um die Ausgabelänge zu steuern, schneiden Sie das Quellvideo zuerst.
size
string
Standard:"16:9"
SeitenverhältnisUnterstützte Formate:
  • 16:9 – Querformat Breitbild (Standard)
  • 9:16 – Hochformat
  • 1:1 – Quadrat
  • 4:3 – Querformat
  • 3:4 – Hochformat
In den Modi I2V / EDIT ignoriert — das Ausgabe-Seitenverhältnis wird automatisch durch das Eingabemedium (Erstbild / Quellvideo) bestimmt
watermark
boolean
Standard:"false"
Soll dem generierten Video ein Wasserzeichen hinzugefügt werden?
  • true: Wasserzeichen hinzufügen
  • false: kein Wasserzeichen (Standard)
seed
integer
Zufallsseed zur Steuerung der Zufälligkeit des generierten InhaltsWertebereich: [0, 2147483647]. Wenn weggelassen, wird ein zufälliger Seed verwendet.
  • Bei identischen Anfragen erzeugt das Modell unterschiedliche Ergebnisse, wenn unterschiedliche Seed-Werte empfangen werden (z. B. ohne Seed)
  • Bei identischen Anfragen erzeugt das Modell ähnliche Ergebnisse, wenn derselbe Seed-Wert empfangen wird, eine exakte Übereinstimmung ist jedoch nicht garantiert

Antwort

code
integer
Statuscode der Antwort, 200 bei Erfolg
data
array
Datenarray der Antwort

Anwendungsfälle

Fall 1: Text-zu-Video T2V (einfachste Anfrage)

{
  "model": "happyhorse-1.0",
  "prompt": "A little girl walking down the road, cinematic feel"
}

Fall 2: Text-zu-Video T2V (vollständige Parameter)

{
  "model": "happyhorse-1.0",
  "prompt": "A coastal road at sunset, slow-motion camera push-in, cinematic feel",
  "resolution": "1080P",
  "size": "16:9",
  "duration": 8,
  "seed": 42
}

Fall 3: Bild-zu-Video I2V (first_frame_image)

{
  "model": "happyhorse-1.0",
  "prompt": "Bring the scene in the image to life",
  "first_frame_image": "https://example.com/first_frame.png",
  "resolution": "1080P",
  "duration": 5
}

Fall 4: Referenz-Bild-zu-Video R2V (mehrere Referenzen)

{
  "model": "happyhorse-1.0",
  "prompt": "The protagonist from image 1 runs through the scene from image 2, then picks up the prop from image 3. Keep a 3D cartoon style with smooth motion.",
  "image_urls": [
    "https://example.com/img_01.jpg",
    "https://example.com/img_02.png",
    "https://example.com/img_03.jpeg"
  ],
  "resolution": "1080P",
  "size": "16:9",
  "duration": 5
}

Fall 5: Video Edit EDIT (Originalton beibehalten + Stilreferenz)

{
  "model": "happyhorse-1.0",
  "prompt": "Convert the character in the video to a cartoon style, preserving the original motion",
  "video_url": "https://example.com/source.mp4",
  "image_urls": [
    "https://example.com/style_ref.jpg"
  ],
  "resolution": "1080P",
  "audio_setting": "origin",
  "seed": 42
}

Fall 6: 720P zur Kosteneinsparung

{
  "model": "happyhorse-1.0",
  "prompt": "Waves crashing on the beach at sunset",
  "resolution": "720P",
  "size": "16:9",
  "duration": 5
}

Leitfaden zur Moduswahl

AnforderungEmpfohlene Vorgehensweise
Video nur aus Text generierenNur prompt übergeben (T2V)
Ein Bild „lebendig” machen (als Erstbild verwenden)first_frame_image übergeben (I2V)
Eine neue Szene aus einer Sammlung von Referenzbildern generierenimage_urls übergeben (1–9, R2V)
Ein vorhandenes Video umschreiben / umstilisierenvideo_url übergeben (EDIT), optional mit image_urls (0–5) als Stilreferenzen kombinieren
Kosten sparenresolution: "720P" verwenden

Tipps zur Nutzung

  1. Logik des einheitlichen Einstiegs: Die Eingabefelder bestimmen den Modus. Beachten Sie, dass die drei Medienfelder (first_frame_image / image_urls / video_url) paarweise gegenseitig ausschließend sind
  2. size wirkt nur in T2V/R2V: In den Modi I2V / EDIT wird size ignoriert — das Ausgabe-Seitenverhältnis wird durch das Eingabemedium bestimmt
  3. Dauer: 5–10 Sekunden ist der optimale Bereich. Zu kurz führt zu ruckartiger Bewegung; zu lang erhöht die Upstream-Verarbeitungszeit erheblich
  4. Qualität des Erstbildes: klar, gut komponiert, Subjekt zentriert — verbessert die I2V-Ausgabe deutlich
  5. Prompt-Formulierung: Beschreiben Sie Bewegung / Kamera / Atmosphäre (z. B. „slow push-in, cinematic, warm tones”) für bessere Ergebnisse als rein statische Szenenbeschreibungen
  6. EDIT-Eingangsvideo: > 15 Sekunden wird vom Upstream automatisch von 0 bis 15s gekürzt. Wenn Sie andere Abschnitte benötigen, schneiden Sie das Video zuerst selbst zu
Aufgabenergebnisse abfragenDie Videogenerierung ist eine asynchrone Aufgabe, die nach der Übermittlung eine task_id zurückgibt. Verwenden Sie den Endpunkt Aufgabenstatus abrufen, um den Generierungsfortschritt und die Ergebnisse abzufragen.