Seedream AI Image Generator API documentation

Generate images with Seedream AI Image Generator (ByteDance). Supports both text and image input modes.

Endpoints

Contract item	Value
Capability	`seedream-ai-image-generator`
Submit	`POST https://vidmage.ai/api/v1/seedream-ai-image-generator/submit`
Query	`POST https://vidmage.ai/api/v1/seedream-ai-image-generator/query`
Task identifier	`taskId`
Result field	`imageUrl`

Authenticate with Authorization: Bearer YOUR_API_KEY. Save the task identifier and query the same capability. Use a stable Idempotency-Key for submission retries.

Product guide: Seedream API

Parameters and input rules

Field	Type	Required	Default	Meaning and limits
`prompt`	`string`	Yes	Not specified	Text prompt describing the image to generate (max 2000 chars). For an unspecified character or figurine, use an original non-branded character with no logos and no resemblance to existing copyrighted superheroes; preserve any character the user explicitly names. Minimum characters: `5` Maximum characters: `2000`
`imageUrl`	`string`	No	Not specified	Optional input image URL. When provided, the task runs in image edit mode.
`imageUrls`	`string[]`	No	Not specified	Ordered input image URLs for image editing mode. The prompt can reference them by their one-based order. Minimum items: `1` Maximum items: `10`
`width`	`integer`	No	`2048`	Output width in pixels; ignored when a resolution tier is selected. Minimum: `512` Maximum: `8192` Multiple of: `8`
`height`	`integer`	No	`2048`	Output height in pixels; ignored when a resolution tier is selected. Minimum: `512` Maximum: `8192`
`sequentialImageGeneration`	`string`	No	`"disabled"`	Allow the model to generate a coherent image sequence. Values: `"disabled"`, `"auto"`
`maxImages`	`integer`	No	`1`	Maximum number of images to generate in a sequence. Minimum: `1` Maximum: `15` Multiple of: `1`
`resolution`	`string`	No	Not specified	Optional output resolution tier; overrides width and height. Values: `"2k"`, `"4k"`

text to image

These are public VidMage field names. The server maps them to provider fields. Input media selects the mode; use its limits together with the parameter table.

Control	Mode-specific rule
`prompt`	Required; 5–2000 characters.
`aspectRatio`	Not used in this mode.
`resolution`	Not used in this mode.
`width`	Output width in pixels; ignored when a resolution tier is selected. Minimum: `512` Maximum: `8192` Multiple of: `8` Default: `2048`
`height`	Output height in pixels; ignored when a resolution tier is selected. Minimum: `512` Maximum: `8192` Multiple of: `8` Default: `2048`
`sequentialImageGeneration`	Allow the model to generate a coherent image sequence. Values: `"disabled"`, `"auto"` Default: `"disabled"`
`maxImages`	Maximum number of images to generate in a sequence. Minimum: `1` Maximum: `15` Multiple of: `1` Default: `1`
`resolution`	Optional output resolution tier; overrides width and height. Values: `"2k"`, `"4k"`

image edit

These are public VidMage field names. The server maps them to provider fields. Input media selects the mode; use its limits together with the parameter table.

Control	Mode-specific rule
`prompt`	Required; 5–2000 characters.
`aspectRatio`	Not used in this mode.
`resolution`	Not used in this mode.
`imageUrls`	Up to 10 files. Formats: jpeg, png.
`width`	Output width in pixels; ignored when a resolution tier is selected. Minimum: `512` Maximum: `8192` Multiple of: `8` Default: `2048`
`height`	Output height in pixels; ignored when a resolution tier is selected. Minimum: `512` Maximum: `8192` Multiple of: `1` Default: `2048`
`sequentialImageGeneration`	Allow the model to generate a coherent image sequence. Values: `"disabled"`, `"auto"` Default: `"disabled"`
`maxImages`	Maximum number of images to generate in a sequence. Minimum: `1` Maximum: `15` Multiple of: `1` Default: `1`
`resolution`	Optional output resolution tier; overrides width and height. Values: `"2k"`, `"4k"`

Example request

{
  "prompt": "Luxury perfume bottle on black stone with soft mist, dramatic studio lighting, premium advertising photography",
  "width": 2048,
  "height": 2048,
  "sequentialImageGeneration": "disabled",
  "maxImages": 1
}

# Set VIDMAGE_IDEMPOTENCY_KEY to a unique value for this task; preserve it for transport retries.
curl -X POST "https://vidmage.ai/api/v1/seedream-ai-image-generator/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Luxury perfume bottle on black stone with soft mist, dramatic studio lighting, premium advertising photography","width":2048,"height":2048,"sequentialImageGeneration":"disabled","maxImages":1}'
# -> { "success": true, "taskId": "...", "creditsConsumed": ... }

Task results and recovery

URL of the generated image. Read imageUrl from the completed query response. Preserve taskId while the task is running.

curl -X POST "https://vidmage.ai/api/v1/seedream-ai-image-generator/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "TASK_ID_FROM_SUBMIT" }'
# -> { "success": true, "data": { "status": "...", "imageUrl": "https://..." } }

Submission and task queries report the available task and usage information. A timeout is not a confirmed failure. Recover the existing task instead of resubmitting.

For face selection and error recovery, follow Task lifecycle. MCP uses the normalized taskId argument in get_task_result, including capabilities whose REST identifier is requestId.

Credits

Component / option	Rate	Minimum
Base rate	10 credits / generation	—

Base charge is per generation at the selected resolution.

maxImages multiplies the base charge by the selected output count.

Use the Playground or the MCP credit estimator for your exact inputs. Credits and billing.

Integration guides

Authentication · File uploads · Task lifecycle · Error recovery · MCP

Seedream AI Image Generator API documentation

Generate images with Seedream AI Image Generator (ByteDance). Supports both text and image input modes.

Endpoints

Contract item	Value
Capability	`seedream-ai-image-generator`
Submit	`POST https://vidmage.ai/api/v1/seedream-ai-image-generator/submit`
Query	`POST https://vidmage.ai/api/v1/seedream-ai-image-generator/query`
Task identifier	`taskId`
Result field	`imageUrl`

Authenticate with Authorization: Bearer YOUR_API_KEY. Save the task identifier and query the same capability. Use a stable Idempotency-Key for submission retries.

Product guide: Seedream API

Parameters and input rules

Field	Type	Required	Default	Meaning and limits
`prompt`	`string`	Yes	Not specified	Text prompt describing the image to generate (max 2000 chars). For an unspecified character or figurine, use an original non-branded character with no logos and no resemblance to existing copyrighted superheroes; preserve any character the user explicitly names. Minimum characters: `5` Maximum characters: `2000`
`imageUrl`	`string`	No	Not specified	Optional input image URL. When provided, the task runs in image edit mode.
`imageUrls`	`string[]`	No	Not specified	Ordered input image URLs for image editing mode. The prompt can reference them by their one-based order. Minimum items: `1` Maximum items: `10`
`width`	`integer`	No	`2048`	Output width in pixels; ignored when a resolution tier is selected. Minimum: `512` Maximum: `8192` Multiple of: `8`
`height`	`integer`	No	`2048`	Output height in pixels; ignored when a resolution tier is selected. Minimum: `512` Maximum: `8192`
`sequentialImageGeneration`	`string`	No	`"disabled"`	Allow the model to generate a coherent image sequence. Values: `"disabled"`, `"auto"`
`maxImages`	`integer`	No	`1`	Maximum number of images to generate in a sequence. Minimum: `1` Maximum: `15` Multiple of: `1`
`resolution`	`string`	No	Not specified	Optional output resolution tier; overrides width and height. Values: `"2k"`, `"4k"`

text to image

These are public VidMage field names. The server maps them to provider fields. Input media selects the mode; use its limits together with the parameter table.

Control	Mode-specific rule
`prompt`	Required; 5–2000 characters.
`aspectRatio`	Not used in this mode.
`resolution`	Not used in this mode.
`width`	Output width in pixels; ignored when a resolution tier is selected. Minimum: `512` Maximum: `8192` Multiple of: `8` Default: `2048`
`height`	Output height in pixels; ignored when a resolution tier is selected. Minimum: `512` Maximum: `8192` Multiple of: `8` Default: `2048`
`sequentialImageGeneration`	Allow the model to generate a coherent image sequence. Values: `"disabled"`, `"auto"` Default: `"disabled"`
`maxImages`	Maximum number of images to generate in a sequence. Minimum: `1` Maximum: `15` Multiple of: `1` Default: `1`
`resolution`	Optional output resolution tier; overrides width and height. Values: `"2k"`, `"4k"`

image edit

These are public VidMage field names. The server maps them to provider fields. Input media selects the mode; use its limits together with the parameter table.

Control	Mode-specific rule
`prompt`	Required; 5–2000 characters.
`aspectRatio`	Not used in this mode.
`resolution`	Not used in this mode.
`imageUrls`	Up to 10 files. Formats: jpeg, png.
`width`	Output width in pixels; ignored when a resolution tier is selected. Minimum: `512` Maximum: `8192` Multiple of: `8` Default: `2048`
`height`	Output height in pixels; ignored when a resolution tier is selected. Minimum: `512` Maximum: `8192` Multiple of: `1` Default: `2048`
`sequentialImageGeneration`	Allow the model to generate a coherent image sequence. Values: `"disabled"`, `"auto"` Default: `"disabled"`
`maxImages`	Maximum number of images to generate in a sequence. Minimum: `1` Maximum: `15` Multiple of: `1` Default: `1`
`resolution`	Optional output resolution tier; overrides width and height. Values: `"2k"`, `"4k"`

Example request

{
  "prompt": "Luxury perfume bottle on black stone with soft mist, dramatic studio lighting, premium advertising photography",
  "width": 2048,
  "height": 2048,
  "sequentialImageGeneration": "disabled",
  "maxImages": 1
}

# Set VIDMAGE_IDEMPOTENCY_KEY to a unique value for this task; preserve it for transport retries.
curl -X POST "https://vidmage.ai/api/v1/seedream-ai-image-generator/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Luxury perfume bottle on black stone with soft mist, dramatic studio lighting, premium advertising photography","width":2048,"height":2048,"sequentialImageGeneration":"disabled","maxImages":1}'
# -> { "success": true, "taskId": "...", "creditsConsumed": ... }

Task results and recovery

URL of the generated image. Read imageUrl from the completed query response. Preserve taskId while the task is running.

curl -X POST "https://vidmage.ai/api/v1/seedream-ai-image-generator/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "TASK_ID_FROM_SUBMIT" }'
# -> { "success": true, "data": { "status": "...", "imageUrl": "https://..." } }

Submission and task queries report the available task and usage information. A timeout is not a confirmed failure. Recover the existing task instead of resubmitting.

For face selection and error recovery, follow Task lifecycle. MCP uses the normalized taskId argument in get_task_result, including capabilities whose REST identifier is requestId.

Credits

Component / option	Rate	Minimum
Base rate	10 credits / generation	—

Base charge is per generation at the selected resolution.

maxImages multiplies the base charge by the selected output count.

Use the Playground or the MCP credit estimator for your exact inputs. Credits and billing.

Integration guides

Authentication · File uploads · Task lifecycle · Error recovery · MCP