Documentation

Create task

POST
/v1/tasks

Authorization

AuthorizationBearer <token>

API key as a Bearer token (Authorization: Bearer ).

In: header

Request Body

application/json

type*string

Task type

Value in"image.watermark"
source_url*string

Public http(s) URL of the source media

Formaturi
idempotency_key?string

Client key to make submission idempotent; a repeat returns the original task

Lengthlength <= 64
params?

image.watermark parameters

webhook?string

URL notified when the task completes

Formaturi
webhook_events_filter?array<>|

Event types to deliver to the webhook (default: all)

[key: string]?never

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://api.fotovid.co/v1/tasks" \  -H "Content-Type: application/json" \  -d '{    "type": "image.watermark",    "source_url": "http://example.com"  }'
{
  "completed_at": "2026-07-16T12:00:04Z",
  "created_at": "2026-07-16T12:00:00Z",
  "data_removed": false,
  "error": null,
  "expires_at": "2026-07-23T12:00:04Z",
  "id": "01JR3F5Z0M8W2K9YQ7B4C6D8E0",
  "metrics": {
    "total_time": 3.2
  },
  "outputs": [
    {
      "kind": "video",
      "url": "https://cdn.fotovid.co/sync/9f8e7d/out.mp4?X-Amz-Expires=900&X-Amz-Signature=e3b0c44298fc1c14"
    }
  ],
  "source": "api",
  "started_at": "2026-07-16T12:00:01Z",
  "status": "succeeded",
  "task_type": "video.trim",
  "urls": {
    "get": "https://cdn.fotovid.co/sync/9f8e7d/out.mp4?X-Amz-Expires=900&X-Amz-Signature=e3b0c44298fc1c14"
  }
}
{
  "code": "VALIDATION_INVALID_ARGUMENT",
  "detail": "source_url is required",
  "errors": [
    {
      "code": "VALIDATION_INVALID_ARGUMENT",
      "field": "source_url",
      "message": "source_url is required"
    }
  ],
  "instance": "/v1/tasks",
  "request_id": "01JR3F5Z0M8W2K9YQ7B4C6D8E0",
  "status": 400,
  "title": "Validation Failed",
  "type": "https://api.fotovid.co/errors/validation"
}
{
  "code": "AUTH_UNAUTHORIZED",
  "detail": "Missing or invalid API key",
  "instance": "/v1/tasks",
  "request_id": "01JR3F5Z0M8W2K9YQ7B4C6D8E0",
  "status": 401,
  "title": "Unauthorized",
  "type": "https://api.fotovid.co/errors/authentication"
}
{
  "code": "INSUFFICIENT_CREDITS",
  "detail": "Not enough credits to run this task",
  "instance": "/v1/tasks",
  "request_id": "01JR3F5Z0M8W2K9YQ7B4C6D8E0",
  "status": 402,
  "title": "Payment Required",
  "type": "https://api.fotovid.co/errors/payment"
}
{
  "code": "RESOURCE_CONFLICT",
  "detail": "A request with this Idempotency-Key is already in progress",
  "instance": "/v1/tasks",
  "request_id": "01JR3F5Z0M8W2K9YQ7B4C6D8E0",
  "status": 409,
  "title": "Conflict",
  "type": "https://api.fotovid.co/errors/conflict"
}
{
  "code": "REQUEST_BODY_TOO_LARGE",
  "detail": "The request body exceeds the maximum allowed size",
  "instance": "/v1/tasks",
  "request_id": "01JR3F5Z0M8W2K9YQ7B4C6D8E0",
  "status": 413,
  "title": "Payload Too Large",
  "type": "https://api.fotovid.co/errors/too-large"
}
{
  "code": "CONTENT_TYPE_UNSUPPORTED",
  "detail": "The source media type is not supported",
  "instance": "/v1/tasks",
  "request_id": "01JR3F5Z0M8W2K9YQ7B4C6D8E0",
  "status": 415,
  "title": "Unsupported Media Type",
  "type": "https://api.fotovid.co/errors/unsupported-media-type"
}
{
  "code": "RATE_LIMIT_EXCEEDED",
  "detail": "Rate limit exceeded; retry after the indicated delay",
  "instance": "/v1/tasks",
  "request_id": "01JR3F5Z0M8W2K9YQ7B4C6D8E0",
  "status": 429,
  "title": "Too Many Requests",
  "type": "https://api.fotovid.co/errors/rate-limit"
}
{
  "code": "INTERNAL",
  "detail": "An internal error occurred",
  "instance": "/v1/tasks",
  "request_id": "01JR3F5Z0M8W2K9YQ7B4C6D8E0",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://api.fotovid.co/errors/internal"
}