> ## Documentation Index > Fetch the complete documentation index at: https://docs.seedhorse.ai/llms.txt > Use this file to discover all available pages before exploring further. # API Reference Generate high-quality AI images and videos with a single HTTP request. This API uses the same generation engine as SeedHorse Studio and is available for developers to call programmatically. ## Capability Overview **Image Generation (Imagen Nano Banana Pro/2)** * **Text-to-Image** — Generate images by inputting text prompts * **Image-Text-to-Image** — Generate images with reference images + text prompts **Video Generation (Seedance 2.0)** * **Image-Text-to-Video** — Generate videos with reference images + text prompts * **Image-Video-Text-to-Video** — Generate videos with reference images + reference videos + text prompts * **Image-Audio-Text-to-Video** — Generate videos with reference images + reference audio + text prompts * **Full-Modality-to-Video** — Generate videos with reference images + reference videos + reference audio + text prompts ## Available Models | Model | Type | Supported Generation Methods (type) | | -------------------- | ----- | ---------------------------------------------------------- | | Imagen Nano Banana 2 | Image | `txt`, `img_txt` | | Seedance 2.0 | Video | `img_txt`, `img_vid_txt`, `img_aud_txt`, `img_vid_aud_txt` | ## Base URL All requests are sent to: ```text theme={null} https://api.seedhorse.ai ``` The API path prefix is `/api/v1`. ## Authentication Each request must carry a Bearer Token in the `Authorization` request header: ```text theme={null} Authorization: Bearer sh-xxxxxxxxxxxxxxxxxx ``` *** ## API Documentation ### Submit Generation Task ```text theme={null} POST /api/v1/task/generate ``` Submit a generation task and return a task ID immediately; the generation process runs asynchronously. #### Request Headers | Header | Required | Description | | ------------------- | -------- | ------------------------------------------------ | | `Authorization` | Yes | `Bearer sh-xxxxx` | | `Content-Type` | Yes | `application/json` | | `X-Idempotency-Key` | No | Idempotency key to prevent duplicate submissions | #### Request Body Parameters | Field | Type | Required | Description | | ----------------- | --------- | -------- | ------------------------------------------------------------- | | `model` | string | **Yes** | Model name (`Seedance 2.0` or `Imagen Nano Banana 2`) | | `taskName` | string | **Yes** | Task name | | `type` | string | **Yes** | Generation method (see [Available Models](#available-models)) | | `prompt` | string | **Yes** | Text prompt describing the content to be generated | | `resolution` | string | No | Video resolution: `720p` (video only) | | `durationSeconds` | integer | No | Video duration (seconds), 4–15 (video only) | | `aspectRatio` | string | No | Aspect ratio: `16:9`, `9:16` (image only) | | `imageCount` | integer | No | Number of images to generate, max 4 (image only) | | `size` | string | No | Image size: `1K`, `2K`, `4K` (image only) | | `quality` | integer | No | Generation quality, 50–100 | | `seed` | long | No | Random seed; `-1` means random | | `generateAudio` | boolean | No | Whether to auto-generate audio (video only, default `true`) | | `refImageUrls` | string\[] | No | List of reference image URLs (max 5) | | `refVideoUrls` | string\[] | No | List of reference video URLs (max 5, video only) | | `refAudioUrls` | string\[] | No | List of reference audio URLs (max 5, video only) | #### Successful Response ```json theme={null} { "code": 0, "data": { "estimatedCredits": 5, "taskId": 9034, "taskNo": "3b248921b9be429b8303838118f3cd7f" }, "msg": "success", "ok": true } ``` | Field | Type | Description | | ----------------------- | ------ | ------------------------------------- | | `data.taskId` | long | Task ID for polling progress | | `data.taskNo` | string | Business task number, globally unique | | `data.estimatedCredits` | long | Pre-deducted credits for this task | *** ### Query Task Status ```text theme={null} GET /api/v1/query/{taskId} ``` Query the current status and generation results of a specified task. #### Request Headers | Header | Required | Description | | --------------- | -------- | ----------------- | | `Authorization` | Yes | `Bearer sh-xxxxx` | #### Successful Response ```json theme={null} { "code": 0, "data": { "aspectRatio": "", "createTime": "2026-04-22T11:01:32", "durationSeconds": 0, "failReason": "", "genMethod": "img_txt", "generateAudio": true, "imageCount": 1, "modelId": 4, "negativePrompt": null, "progress": 100, "prompt": "A grey kitten", "quality": 80, "refAudioUrls": [], "refImageUrls": [], "refVideoUrls": [], "resolution": "720p", "results": [ { "durationSeconds": 5, "failReason": "", "fileUrl": "https://tk-hub.oss-ap-northeast-1.aliyuncs.com/tasks/files/.../task_xxx.mp4?...", "height": 0, "subStatus": 0, "thumbnailUrl": null, "width": 0 } ], "seed": -1, "size": "", "subTaskDone": 0, "subTaskTotal": 0, "taskId": 9055, "taskName": "Image-Text Video Generation", "taskStatus": 2, "taskType": 1 }, "msg": "success", "ok": true } ``` #### Response Field Description | Field | Type | Description | | -------------------------------- | --------- | ------------------------------------------------------------------------------------------- | | `data.taskId` | long | Task ID | | `data.taskName` | string | Task name | | `data.taskStatus` | int | Task status (0=Queuing 1=Generating 2=Completed 3=Failed 4=Under safety review 5=Cancelled) | | `data.taskType` | int | Task type (1=Video 2=Image) | | `data.progress` | int | Progress percentage (0–100) | | `data.modelId` | long | ID of the used model | | `data.genMethod` | string | Generation method (e.g. `img_txt`, `txt`) | | `data.prompt` | string | Positive prompt | | `data.negativePrompt` | string | Negative prompt (nullable) | | `data.resolution` | string | Resolution (video task) | | `data.durationSeconds` | int | Video duration (seconds) | | `data.aspectRatio` | string | Aspect ratio | | `data.imageCount` | int | Number of generated images | | `data.size` | string | Image size | | `data.quality` | int | Generation quality (50–100) | | `data.seed` | long | Random seed (-1=Not specified) | | `data.generateAudio` | boolean | Whether to auto-generate audio | | `data.refImageUrls` | string\[] | List of reference image URLs | | `data.refVideoUrls` | string\[] | List of reference video URLs | | `data.refAudioUrls` | string\[] | List of reference audio URLs | | `data.failReason` | string | Failure reason (populated on failure) | | `data.subTaskTotal` | int | Total subtasks (valid for multi-image tasks) | | `data.subTaskDone` | int | Completed subtasks | | `data.createTime` | string | Creation time | | `data.results` | array | Generation result list (populated when completed) | | `data.results[].fileUrl` | string | Result file URL | | `data.results[].thumbnailUrl` | string | Thumbnail URL | | `data.results[].durationSeconds` | int | Video duration (seconds) | | `data.results[].width` | int | Width (pixels) | | `data.results[].height` | int | Height (pixels) | | `data.results[].subStatus` | int | Subtask status (0=Pending 1=Success 2=Failed) | | `data.results[].failReason` | string | Subtask failure reason | > It is recommended to poll every 5–10 seconds until `taskStatus` becomes `2` (Completed) or `3` (Failed). *** ## Quick Start ### 1. Submit Task ```bash theme={null} curl -X POST https://api.seedhorse.ai/api/v1/task/generate \ -H "Authorization: Bearer sh-xxxxx" \ -H "Content-Type: application/json" \ -d '{ "model": "Seedance 2.0", "taskName": "My First Video", "type": "img_txt", "prompt": "A cinematic tracking shot through a neon-lit rainy street at night", "durationSeconds": 5, "resolution": "720p", "aspectRatio": "16:9", "generateAudio": true }' ``` ### 2. Poll Status ```bash theme={null} curl https://api.seedhorse.ai/api/v1/query/9034 \ -H "Authorization: Bearer sh-xxxxx" ``` ### 3. Get Results When `taskStatus` is `2`, the `results` array contains the URLs of the generated files. Please download and save them to your own storage as soon as possible. *** ## Request Examples ### Image Generation #### Text-to-Image (txt) ```json theme={null} { "model": "Imagen Nano Banana 2", "taskName": "Image Generation Test", "type": "txt", "prompt": "a cute orange cat sitting on a windowsill, warm sunlight, studio ghibli style", "aspectRatio": "9:16", "imageCount": 1, "size": "4k" } ``` #### Image-Text-to-Image (img\_txt) ```json theme={null} { "model": "Imagen Nano Banana 2", "taskName": "Image-Text Generation Test", "type": "img_txt", "prompt": "Generate a blue kitten", "aspectRatio": "9:16", "refImageUrls": ["https://example.com/reference.jpg"], "imageCount": 1, "size": "4k" } ``` ### Video Generation #### Image-Text-to-Video (img\_txt) ```json theme={null} { "model": "Seedance 2.0", "taskName": "Image-Text Video Generation", "type": "img_txt", "prompt": "A grey kitten playing in the garden", "durationSeconds": 5, "resolution": "720p", "aspectRatio": "16:9", "generateAudio": true, "refImageUrls": ["https://example.com/cat.jpg"] } ``` #### Image-Video-Text-to-Video (img\_vid\_txt) ```json theme={null} { "model": "Seedance 2.0", "taskName": "Image-Video-Text Video Generation", "type": "img_vid_txt", "prompt": "A grey kitten", "durationSeconds": 5, "resolution": "720p", "aspectRatio": "16:9", "generateAudio": true, "refImageUrls": ["https://example.com/cat.jpg"], "refVideoUrls": ["https://example.com/reference.mp4"] } ``` #### Image-Audio-Text-to-Video (img\_aud\_txt) ```json theme={null} { "model": "Seedance 2.0", "taskName": "Image-Audio-Text Video Generation", "type": "img_aud_txt", "prompt": "A grey kitten", "durationSeconds": 5, "resolution": "720p", "aspectRatio": "16:9", "generateAudio": true, "refImageUrls": ["https://example.com/cat.jpg"], "refAudioUrls": ["https://example.com/music.mp3"] } ``` #### Full-Modality-to-Video (img\_vid\_aud\_txt) ```json theme={null} { "model": "Seedance 2.0", "taskName": "Full-Modality Video Generation", "type": "img_vid_aud_txt", "prompt": "A grey kitten", "durationSeconds": 5, "resolution": "720p", "aspectRatio": "16:9", "generateAudio": true, "refImageUrls": ["https://example.com/cat.jpg"], "refVideoUrls": ["https://example.com/reference.mp4"], "refAudioUrls": ["https://example.com/music.mp3"] } ``` *** ## Error Codes Unified response format: ```json theme={null} { "code": 40003, "msg": "Seedance 2.0 model does not exist", "ok": false, "data": null } ``` ### System Errors (1xxxx) | Error Code | Description | | ---------- | ---------------------- | | 10001 | System busy | | 10006 | Failed to acquire lock | ### Authentication/Authorization (2xxxx) | Error Code | Description | | ---------- | ---------------------------------- | | 20001 | Not logged in or login expired | | 20002 | No access permission | | 20003 | No permission to operate this task | | 20008 | Invalid API Key | ### Parameter Validation (3xxxx) | Error Code | Description | | ---------- | ---------------------------------------------------------------------- | | 30001 | Invalid parameters (missing required fields or wrong parameter format) | ### Resource Not Found (4xxxx) | Error Code | Description | | ---------- | ---------------------------------------- | | 40002 | Task does not exist | | 40003 | Model does not exist or has been offline | ### Business Rules (5xxxx) | Error Code | Description | | ---------- | -------------------------------------- | | 50001 | Model disabled | | 50002 | Channel unavailable | | 50003 | Generation method not supported | | 50006 | Resolution not supported | | 50007 | Duration not supported | | 50008 | Image size not supported | | 50009 | Aspect ratio not supported | | 50010 | Invalid image count | | 50011 | Reference image required | | 50014 | Reference content failed safety review | | 50015 | Reference content blocked | ### Credit Billing (6xxxx) | Error Code | Description | | ---------- | ------------------------------- | | 60001 | Insufficient credits | | 60002 | Billing lock busy, please retry |